The First Two Questions (Was: Design Document)

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

At 9:33 AM -0500 12/17/98, sheldon kohn wrote:

>Summary of My Request for Input
>
>My challenge is to create a "design document" for a new Java product. The
>development team is required to prepare and present a "design document," but
>the requirements for it are not clear. My request was for input from people
>on the list as to how I might best define this document.
>
>Summary of Responses
>
>One idea is to create a graphics-intensive document and to focus on how the
>product helps users now and how it is being designed to meet the
>organization's needs in the future.
>
>Another suggestion is to follow JoAnn Hackos' framework for managing a
>documentation project.
>
> . . .
>
>Another suggestion is to begin by producing a design object model, though
>this will take a good bit of time with the developers and myself hashing
>things out on a white board. The design object model shows the relationships
>between the key classes and how these relationships are to be designed and
>implemented in the code. This responder found object-oriented analysis and
>design to be inherently interesting, and I have to say that I agree.

I'm wondering if the responses (I omitted most of them) were so
radically different from each other because no two respondents
had the same idea about what you were talking about.

So let's go back to the First Two Questions to answer before
writing any technical document:

   1. Who is supposed to read this document?

   2. What job will they be performing with the information?

"Design Document" can mean many things to many different people.

One type of "design document" is an interface design: a
description of all the rules for how the computer's input/output
devices are to behave while the computer is running a program yet
to be written.  That's the kind of information that programmers
need in order to write a program.  Alas, most companies skip
interface design, blurring it with requirements or thinking that
requirements give the programmers all the information they need.
If this is the kind of document you want to write, then your SME
is the interface designer.

Another type of "design document", especially as the term is used
by programmers, is a description of a "high-level design" of a
program, to to be read by a certain kind of programmer, called a
"coder", to tell them what subroutines to write and what these
subroutines' inputs and outputs should be.  In this case, your
SME would be the programmers who invented the high-level design:
the classes, subroutine specifications, and so on.

I think that this latter type of design document is best kept
very, very short if it exists at all--just some diagrams with a
wee bit of accompanying text, just enough to help the programmers
write code.  The best design documentation is right inside the
source code, where it's short, to-the-point, and up to date.  In
fact, well-written code is itself the best design documentation.
Some companies spend a lot of time making lengthy design
documents, only to find that they mostly contain useless
information (that's what happens when people don't answer the
First Two Questions), and the useful information is out of date
almost immediately.  The source code is *always* up to date, by
definition.

An interface design, however, needs to be super-detailed and it
needs to be a document separate from the source code.
Programmers refer to a well-written interface design document
almost constantly, especially during high-level design.

But it's very hard to suggest anything without having answers to
the First Two Questions.  How do the other people on the team
answer them?

--
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=