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: Developer Documentation From:Jean Weber <jhweber -at- WHITSUNDAY -dot- NET -dot- AU> Date:Tue, 23 Mar 1999 09:48:53 +1000
I have found all of these useful: requirements specifications, functional
specs, design documents, use
cases. But only if those documents contain the information I need, clearly
written and complete.
Developer documents are often improved by having someone on the writing
team involved in writing (or at least editing) them. The developers are
more likely to assume knowledge that a writer may not have but will need.
If writers are involved, they can question these assumptions at this stage,
and (assuming they get an answer) include the necessary information in the
developer docs. (And sometimes writers can influence the design, before
it's in code and will require rework.) Also, even minor rewording of some
developer material may make it more useful to the developers as well as to
the writers (for example, consistent use of terminology, or detailed
step-by-step procedures in use cases).
If you offer to do the rewriting and formatting of the developer docs, the
developers might decide that you save them more time than it takes to
explain a few things to you. And, as always, use the approach that what you
do makes _them_ look good.
