Re: Sample software requirement docs.

Subject: Re: Sample software requirement docs.
From: Ben Kovitz <apteryx -at- CHISP -dot- NET>
Date: Sat, 19 Dec 1998 02:39:01 -0700

Smokey Lynne L Bare's manager asketh:

>Application development is looking for a sample that has detailed
>requirements, something a programmer can actually program from. This is
>also to be used as an example for the functional people to show where
>they presently are......and where they should really be.
>Presently, application development is receiving high-end functional
>requirements vs the needed technical requirements. "This is what I need
>to gather for them."

What programmers need to program from is a detailed--and I mean
detailed--description of the rules of behavior of the input/output devices
of the machine to be programmed. I call this an "interface design
document". I agree that a requirements document is not enough to code
from, especially if it's "high-end".

I think the best person to prepare an interface design document is the
interface designer. While it can help to have a professional tech writer
help out, what makes the document useful is its contents, and its contents
are purely made-up stuff. So it's easiest if the person who made it up is
also the one to write it up.

The problem with these documents is generally not formatting or
organization. It's usually that the document either doesn't exist, or the
person who made up the interface design didn't think the details through
far enough. That is, what's wrong is usually more an inventing-the-design
problem than a writing problem. ISO and MIL standards generally don't help
with this, by the way. You make a good design by making a good design, not
by following documentation standards.

My book (links in .sig below) includes excerpts from a user-interface
design document from a small, real project. The programmer loved it (also
the tester and documenter). It was open, on her desk next to her computer,
and filled with implementation notes every time I walked by her office.
Also, everyone involved read the whole thing and had lots of
content-related (as opposed to format-related) suggestions for it at the
design review.

It's not perfect, though. The original document was 80 pages. For reasons
of space, I excerpted only about 20 pages. And they set it in Adobe
Garamond, which I do *not* recommend for internal documentation! But it's
still useful, in that it shows you what's involved in documenting every
field, every button, every error message, every menu item, and so on.
However, I think the more useful stuff is the sections that explain what a
requirements document needs to contain and what an interface design
document needs to contain.

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: Researching the subject (Was: Respect, "Returns", "Includes", "Increment", usage questions, and many more)
Next by Author: Re: Imagine you teach
Previous by Thread: Sample software requirement docs.
Next by Thread: Researching the subject (Was: Respect, "Returns", "Includes", "Increment", usage questions, and many more)

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

Sponsored Ads