Re: The user guide prescribes the program

Subject: Re: The user guide prescribes the program
From: David Wernick <tirza -at- NETMEDIA -dot- NET -dot- IL>
Date: Tue, 7 Jan 1997 20:46:39 +0200

Joe Rapp wrote:

> Can someone provide a reference that supports the following
> view?
> An experienced engineer/manager at NYNEX told me that
> he believes that "The documentation IS the program." This
> means that, for example, on a $60 million software project, they
> FIRST wrote the user guide and designed the screens. Then
> the users tested the guide for usefulness, clarity, etc. This
> first phase took a year and a half. AFTER this was done, the
> programmers were told to write the code -- which they did in
> two weeks.


What you are describing is the classic "waterfall" model for software
development. According to this model, the development team should first
prepare requirements, specifications, and design documents for the software.
In strict implementations, the design documents include a detailed user's
guide. This is not the polished manual that is shipped with the software,
but it should specify exactly what the user does and what happens for every
feature of the software.

Then, the software is coded and tested against the design. There are a
number of review and feedback stages, in which the developers can go back
and revise the design if required.

The waterfall model was strictly enforced at some companies 15 and more
years ago. The model has been modified and made less strict in recent years,
with techniques such as interface prototyping partly replacing the formal

The waterfall model is a time-tested way to produce bug-free software. It
works, but it is expensive to implement strictly. In practice, how many
companies follow the formal review, revision, and testing procedures? I
don't know. Large companies that develop for critical applications, such as
NYNEX, are among the prime adherents. In some companies, technical writers
work together with the programmers to write the design documentation.

In my experience, even the smallest companies write some form of design
documentation. Unfortunately, it's often not good enough to test the
software or the final user's guide against it. If you can have an influence
in this regard, you will be doing a service not only to our profession but
to the entire world of software users.

You can find a discussion of the waterfall model and its modifications in
many textbooks on software development. For recent information, look in
journals such as Communications of the ACM. For a definitive discussion, see
the ISO quality management standard for software development (ISO 9000-3).

David Wernick

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
Search the archives at or search and
browse the archives at

Next by Author: Re: The user guide prescribes the program
Previous by Thread: Re: The user guide prescribes the program
Next by Thread: Re: The user guide prescribes the program

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads