TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: The user guide prescribes the program From:David Wernick <tirza -at- NETMEDIA -dot- NET -dot- IL> Date:Thu, 9 Jan 1997 21:08:35 +0200
John Bell responded to my post about the waterfall model:
> 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.
John,
You're right, if by "user's guide" you mean the final, polished document
that is given to the customer with the software. But many companies produce
a "design document" that is essentially a very rough draft of the user's
guide. Some of them even call it a "draft user's guide".
The document may be disorganized, poorly written, or use a lot of technical
language, but (in theory) it should be complete and accurate. If the
programmers revise the design, they're supposed to go back and revise the
design document. As you said - the programmers, the testers, and the writers
all work from the design.
I'd be interested in hearing from Joe Rapp, who started this thread, whether
the NYNEX "user's guide" was a design document or a polished customer
manual.
David Wernick
TIRZA
Developers of:
* User's Guides * Technical Manuals * Online Documents *
* Custom MS Word Macros * Authoring Tools *
POB 443, Elkana 44814, Israel
tel: 972-3-9362170
email: tirza -at- netmedia -dot- net -dot- il
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
