RE: Release notes: term for bugs

["Jonathan West" <jwest -at- mvps -dot- org>]

> >
> > Johnathon West wrote:
> > In some small shops, it is only as they write the code
> > that they *discover* how they want it to work. The
> > design follows the writing of the code, not the other
> > way around....There was *nothing* in the entire place
> > written down as to what the product was meant to do.
> >
> > --------------------------------------
> >
> > You're the third person, aside from myself, who has
> > mentioned working in a place that operated like that.
> > I'm wondering how many places out there are like this.
>
> For some problems, that may be the right method. You need
> an iterative approach. Build a prototype, play with it,
> learn some things, build a better one, ...
>
> You don't know enough at the start to write a good spec,
> and you're better off trying to learn more than writing
> a bad one.

What you are doing is describing the distinction between software research &
software development.

Research is where you really don't know whether what you want to do is
possible or practicable, so you experiment and try things in order to find
out what approximation to your inital thoughts can actually be done.

Development is where you know what you want to do, know that it is possible,
and you want it done as thoroughly, quickly and cheaply as possible.

Even with development, a written spec is not necessary provided the
development team is no more than three people who know each other very well
and have a common understanding of what they are doing.

Anything more than 3, and IMO you really need to start writing things down.
Most particularly, you need to write down:-

- What the user will see, either on the screen, if the user is a human user,
or in  the API, if it is a programmable component

- what the interfaces are between the functional blocks that are written by
different people

Finding and fixing design problems at the QA testing stage is horribly
time-consuming and expensive, and gets ever more so as a product gets larger
and more complex.

The problem that I saw in the job last year was that the company had used
venture capital to grow from a 2-3 person company up to 25 people (15 in
dev/QA, 10 on sales, marketing & admin), without realising that growing to
that size requires a change in the way the development process works,
because you need clear communication and division of responsibilities
between a larger number of developers.

I suspect that many companies have these kinds of "growing pains", and that
a proportion of them fail because they don't learn fast enough. I expect
that it was a contributory factor in the failure of many of the dotcoms.

Technical writers IMO have a valid input in terms of persuading their
companies of the need to write design specs, and being in a position to help
with getting the information written down clearly and unambiguously. A tech
writer who successfully persuades a growing company to do this can probably
claim that the company has been saved by his or her efforts. Tech writers as
heros - how about that?

Regards
Jonathan West


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.