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: Dev. Cycle and the Manual From:"Jeanne A. E. DeVoto" <jaed -at- JAEDWORKS -dot- COM> Date:Tue, 4 May 1999 12:32:34 -0700
At 9:19 AM -0700 5/4/99, Lief Erickson wrote:
>Is it possible to have a user's manual near completion at the end of the
>requirements phase of development? [...] five software development
>phases: analysis, requirements, design, coding, and testing.
Erm. You seem to be asking whether the manual can be complete before the
design phase is begun. Offhand, I would say, "Probably not." ;-)
More generally, in theory it is possible to document a product from a
complete external specification - that is, a spec that describes what the
software looks like and how it acts, as opposed to an internal spec that
describes its inner workings, algorithms used, etc.
However, in real life two major factors prevent this from working well at all.
The first is the problem a couple of people have already mentioned, that
the software invariably deviates from the spec as development progresses. A
feature may need to be removed because of intractable bugs plus an
inflexible ship date, or user testing may reveal that part of the interface
is harder to use than anticipated, or features may be added at the last
minute. It's possible for an organization to be very disciplined about
following the spec, but this inflexibility may result in an inferior
product unless the spec is written by highly experienced wizards.
The second problem is that reading a specification is not at all the same
experience as working with the software. Once the writer has a chance to
play with an actual build, it may become clear that certain portions of the
documentation need to be reworded or reorganized because they don't make as
much sense as they seemed to when the writer was reading the spec and only
imagining what using the software would be like. This problem can be worked
around to some extent if the developers provide a prototype of the software
as part of the design effort, but factors not in the prototype, such as
unexpected lag time when using a feature, can still come back to bite you.
--
jeanne a. e. devoto ~ jaed -at- jaedworks -dot- com http://www.jaedworks.com
Wake up and smell the grztlfrb, earth being.
