Re: The user guide prescribes the program

[John Bell <john_bell -at- C-STONE -dot- COM>]

I'm a little leery of this approach.

Oh, it sounds good on the surface, but it has one major flaw.
Who designs the software?

The concept of having the user guide be the model for the software
implies that whoever writes the user guide is therefore the designer
of the software. As much as I'd like that kind of job, I seriously
doubt experienced, high-paid programmers are going to accept their
marching orders from their friendly tech writer.

Software design is a specialty all by itself. Good designers produce
some really useful and intuitive programs. Companies that can't afford
good designers muddle through the best they can. Usually the programmer
with the best design talents gets the role of designer, although I
have witnessed a few software projects where the designer was the
manager.....just because.

Although I've done some programming, I would not cast myself in the
role of designer. It takes more than just being the user advocate to
design solid, usable software. I think that as a user advocate I make
a good advisor to a designer, but not a replacement for one.

One person who responded mentioned the waterfall process. In the
ideal waterfall process you take these steps:
1) Get requirements (produce requirements document)
2) Analyze requirements (produce specifications)
3) Design the software (produce design document)
   The design doc then goes to the programmers, the tech writers,
   and the testers. They each do their magic on it in parallel.
4a) the programmers produce the code
4b) the tech writers produce the user's guide
4c) the testers produce the test plan.
5)  During coding, the programmers typically discover that the design
    can't be implemented as documented. Either the method just doesn't
    work, or it runs too slowly or unreliably to meet the specs.
    Thus, any deviations from the design they have to document.

Step 5 might be a major task if the user's guide is to be the design
doc. The idealistic approach one might take when writing the user's
guide may not be practically implemented. Yes, I'd love the software
to do XYZ for me automatically, but the cost (in terms of user time or
programmer time) might not be worth it.

Another thought that hit me. The user guide cannot be the complete
design doc because it doesn't include any of the "behind the scenes"
design issues like database schema, access algorithms, and so on.
You still need a software designer to resolve those issues.

I'm not trying to be negative for the sake of being negative. I am
trying to point out that using the user's guide as the design doc has
the effect of casting the tech writer in the role of software designer.
If the tech writer is skilled as a designer, this can work.

--- John Bell
    john_bell -at- c-stone -dot- com

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html