Design Documents
Hi guys,
[This is a long document. I have worked on this rather than
setting up a meeting wit my contractor;-), please do not
dismiss this]
I have spent my weekend a) looking for furniture, b) packing,
and c) reading the documentation on deity, and d) looking for a
design doc for deity.
I failed on a (don't people _like_ confortable dining chairs
anymore?) and d.
I think that we need a document that details the overview of
the design for Deity, and which details the requirements and
specifications of the project. (actually, I'm mildly appalled that
there _is_ no such document). I disagree with Frederick Brooks on a
number of points, (I think he is out of date), but I do concede that
conceptual integrity is important. Or at least that the lack of it
has often been disastrous.
I have been called in onto trouble shoot various projects of
varying sizes, and the ones with the most egregious cost and schedule
over runs were the one with no solid core documentation.
The excuses cited were many: we all know what we want to
do. Well, it is easy to forget little details when it is all in
somebodies head. And people leave the project. People join. Without
the documentation, it is hard to manage things. The documents can be
used to showcase the inevitable creeping featurism, as well as to
design how to integrate the changed specs into the project. The
design docs can be used to validate the final product. They are of
immeasurable value for the maintainers (who are rarely the authors).
It has been said it takes more time. I have never seen that to
be the case. The time spent in writing the design docs is repayed
several times over in saved debug time, and gratituous hacks required
to fit in a feature which was forgotten.
It is said that the project is too small to write a design
document. Any project with more than two people involved is not too
small. I am conservative about this. Any project taking more than a
5 day man week can not be said to be too small to derive benefit from
the design documents. And, if it is a small project, the requirements
/ design s going to be short as well.
Also, writing the design down helps clarify it. We can't
afford this part of Debian not to be clearly designed.
Writing a design document helps open up the process to peer
review. (If you read the mythical man month [be sure to get the 1995
edition], I think the surgeons would benefit from peer review. the
surgeon model is based in the dark ages. read about the guy who had
the wrong leg amputated? there were a series of snafus reported in
the last *year*). I have seen to many projects saved by peer review
to advocate developing in semi secret.
Yes, I would be happier if this were done in may. But it was
not. I strongly object to hacking on, wily-nily, just because we are
late. Being behind schedule is no justification for sloppiness. Not
having a design is sloppy.
Any software project needs to spend an estimated 40% of the
total time gathering and detailing requirements, operational
parameters and specifications, and setting down and validating a
design. (Admittedly, these figures are for non-trivial projects,
7 digit LOC counts or more, but I do not think the figure goes down
significantly until you reach toy software dimentsions <10K LOC).
Good design documents include thigs like the requirements for
the product, often determined in language-independent terms. In fact,
the requirements should guide the language the product is coded in.
It should detail the procedural description, and or the data
flow and conversion paths of the product. This helps refine the
requirements, and sets the stage for the next step.
Detailing the components (objects, modules) of the design, and
the interface definition of these modules.
Lastly, for maintainence purposes, each modules should
document internal proedures, etc.
If, as I am assured, in this case, the Deity ream is well
versed in the procedural and data flow models of the product, then it
should take no time at all to flesh out the skeleton I'll be sending
out later today.
flames welcome.
manoj
leaving to see his contractor, but will be back to draft the outline
of the design doc.
--
"I will contend that conceptual integrity is *the* most important consideration
in system design." Frederick Brooks, Jr., _The Mythical Man Month_
Manoj Srivastava <url:mailto:srivasta@acm.org>
Mobile, Alabama USA <url:http://www.datasync.com/%7Esrivasta/>
Reply to: