Re: When Worlds Collide: McConnell meets Hacko
My immediate response is colored by the fact that I==================================================
have mainly worked in large organizations. That said,
my feeling is that if they want someone to write a
functional spec, they should hire or assign someone
to do that. Obviously, the spec needs to be written
early because so many groups depend on it to do
their own jobs, and the engineers themselves should
have it to write the code against.
However, specs are not user's guides. The reason Hackos
recommends that writers not write detailed information
for the end user in early stages of the project is that
nearly all of it will have to be rewritten as the
product changes.
Nevertheless, a qualified engineering writer who produces a functional
spec early in the program, and who can also write end-user documentation
is likely to produce a more usable functional spec, and that spec can
be used from the outset by the end-user documentation group as a
point of departure. In fact, when I've been responsible for producing both
functional specs and the end-user documentation on the same project,
I continue, as the project evolves, to update and expand the functional
spec to serve as a repository of information that will be needed in the
end user docs. At the appropriate point in the development process,
this primordial end-user doc is reorganized to become the initial version
of the actual end-user doc.
It helps, of course, if the original functional spec,
the primordial end user doc, and the "real" end-user doc
are all structured docs (e.g., SGML or XML) which share a
common DTD/EDD. That eases the process of reusing and
repurposing the information, using FrameMaker+SGML as the
authoring tool for all of them.
====================
| Nullius in Verba |
====================
Dan Emory, Dan Emory & Associates
FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Voice/Fax: 949-722-8971 E-Mail: danemory -at- primenet -dot- com
10044 Adams Ave. #208, Huntington Beach, CA 92646
---Subscribe to the "Free Framers" list by sending a message to
majordomo -at- omsys -dot- com with "subscribe framers" (no quotes) in the body.
Previous by Author:
Re: FrameMkr question-formats
Next by Author:
Re: When Worlds Collide: McConnell meets H
Previous by Thread:
Re: When Worlds Collide: McConnell meets Hacko
Next by Thread:
Internationalization and multiple source bases
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads