Path: utzoo!attcan!utgpu!news-server.csri.toronto.edu!mailrus!uwm.edu!zaphod.mps.ohio-state.edu!usc!ucsd!ucbvax!TRANSARC.COM!Dean_Thompson
From: Dean_Thompson@TRANSARC.COM
Newsgroups: comp.software-eng
Subject: Amount of Design Documentation
Message-ID: <Eail8ur0BwwAEiGEo8@transarc.com>
Date: 4 Aug 90 18:21:46 GMT
Sender: daemon@ucbvax.BERKELEY.EDU
Lines: 31

Based on your experience, how much design documentation do you think should
be done before coding starts?  Consider the following levels:

"high level" -- Describe important algorithms and data structures.  List the
                modules with a short prose description of what each will do.

"module level" -- In addition, give an exact interface for each module.

"detail level" -- In addition, describe the important algorithms and data
                  structures for each module.  Use psuedocode when it is the
                  best way to clearly describe the intended implementation.

I am interested in your experience with:

  - How long a particular level of design documentation takes.

  - How much of this time is repayed by faster coding.

  - How particular levels of design documentation influence the ultimate
    buginess of the code.

  - How particular levels influence the ultimate cleanliness of the code
    structure.

  - How useful particular levels turn out to be for maintenance.

I'm much more interested in specific experiences than philosophy.

Dean Thompson
Transarc Corporation
dt@transarc.com