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.
Re: New How To Information: Programming Manuals and Requirements Definitions Docs
Subject:Re: New How To Information: Programming Manuals and Requirements Definitions Docs From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Mon, 1 Mar 1999 21:50:41 -0700
Nina Panzica wrote:
>Does anybody know of any good books or Web sites that provide:
>
>(a) Information on how to write a programming manual. (By that I mean =
>the documentation of a large custom database system composed of modules =
>written in six or seven different languages so that if or when the guy =
>who created this thing leaves someone else will be able to step in and =
>understand it well enough to maintain it and to add to it.) I'm =
>particularly interested in finding out what kinds of information such a =
>manual must contain to be of any use to a replacement programmer. I'll =
>be getting my information from a very smart but also very busy =
>programmer, so I need to know what sorts of questions to ask him. I also =
>don't know a lot about programming so I need info. that's on a pretty =
>basic level.
>
>(b) Information on how to write a thorough requirements definitions =
>document. Once again, what categories of information do these documents =
>need to contain to be useful when the programmers move to the design =
>phase? The goal here is to make it as complete as possible, give them =
>more info. than they need, if possible. If it's of any help, the =
>designers will be plugging the information collected into this document =
>into a tool called "Rational Rose." (sp?) The info. will be gathered at =
>a series of meetings with the representatives of the organization =
>purchasing the customized product.
Alas, programmer documentation is one of my main passions, but I don't know
of any systematic coverage of how to do it.
I have, however, written a book specifically about what information a
requirements document needs to contain to be of use to programmers. Links
to relevant web pages are in my .sig below. The publisher maintains an
Author On-Line forum when I answer specific questions. If you post
something specific about your project, I might be able to point you in a
helpful direction even on the programmer documentation.
Here's one of the main principles about requirements and programmers,
though: the *interface design* is the much-neglected step that comes
between requirements and programming. The requirements define the problem
solved by the interface design; the interface design solves the problem
that is of immediate interest to programmers.
