Re: The First Two Questions (Was: Design Document)

[Ben Kovitz <apteryx -at- CHISP -dot- NET>]

Amy Poos replied to me:

>Which one of these is the document that I (the technical writer who does not
>write design documents) use? I am expected to review what's in store, to
>provide feedback on the plan from a user's perspective and from a logical
>perspective, and to start writing the documentation before I see what is
>really developed.
>
>My concept of a design document is a document that all groups provide input
>to and all groups use to do their jobs. In my software development
>environment, these groups include Marketing, Development, Documentation,
>Test/QA, Customer Support, and Training. Is this totally out of line with
>what other companies do?

Well, as I was saying, the term "design document" means many things to many
different people.

The document that is, or rather should be, of interest to *everyone* on the
project is what I call a requirements document.  That's the one that talks
about the problem domain and what the software is supposed to accomplish
there.  Everyone should contribute to that one and everyone should have
some reason to look at it.  If your company makes documents like this,
you're only "out of line" with other companies in that you're doing a way
better job than most!  In fact, can I come work there?

Another type of document is what I call an "interface design".  For a
graphical user interface, this document shows screen shots and describes
what happens when the users does every possible action with every
thingamajig on the screen.  This sort of document is generally too terse
and detailed for marketing or for the customer, but it's crucial for the
programmers, testers, and documentation writers.  It's crucial for the
latter group because it lists each operating procedure for the software.
Well, it should.  Crucial as this information is, few companies think it
through, much less write it down so that the people who need it can have it.

And still another type of document describes the program itself: it
structure, the various parts that send data to other parts, the data that
they send, the way that information is represented inside the computer, and
so on.  This information is of use only to programmers and testers.  No one
else has any reason to care about it, and the testers only care because it
helps them think of likely mistakes that the programmers might make.

In my somewhat idiosyncratic view, each of these documents is about a
"design".  Each describes the fruit of some sort of human creativity.  The
difference between them is the subject matter.  The requirements document
talks about the problem domain; the, er, third document talks about how the
machine domain is going to be configured; and the interface design talks
about the overlap between the problem domain and the machine domain.

So I never call anything simply a "design document".  My own policy is to
always add a qualifier: "interface design document" or "program design
document".

There is really no standard terminology or standard set of contents for any
document or even a standard way to divide the information across documents
or even standard material to talk or even think about except the program
code itself.


(There's actually a good reason why the third kind of document is the one
most often called simply "design document" and why it's heresy to call the
requirements just another type of "design" as you and I both seem to.  But
today that reason has almost disappeared into the clouds of history, and
few people know or care what it is.)

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Author,  _Practical Software Requirements: A Manual of Content & Style_
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz


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