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.

Ben Kovitz <apteryx -at- chisp -dot- net>
Author, _Practical Software Requirements: A Manual of Content & Style_

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: javascript help list
Next by Author: Re: Documenting Code/Why Is It So Ugly?
Previous by Thread: New How To Information: Programming Manuals and Requirements Definitions Docs
Next by Thread: Wanted: Proposal Reviewers for FORUM 2000

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

Sponsored Ads