Path: utzoo!utgpu!news-server.csri.toronto.edu!mailrus!cs.utexas.edu!uunet!pilchuck!amc-gw!thebes!polari!jjj From: jjj@polari.UUCP (Jeff J) Newsgroups: comp.software-eng Subject: Re: Amount of Design Documentation Summary: Requirements and risk Message-ID: <2314@polari.UUCP> Date: 6 Aug 90 16:23:18 GMT References: Organization: Seattle Online Public Unix (206) 328-4944 Lines: 41 In article Dean_Thompson@TRANSARC.COM writes: >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. In my experience the biggest problems have come at the beginning of the project life cycle. If the initial analysis and requirements are not done with care all the design documentation in the world will not be worth anything. The most important place to put in the time documenting and to have objective reviews is in the early phase of a project. Any mistakes made here are a lot more costly then those made at the coding level. A code bug is easy to fix. A design error is far more costly. Of course this has to be balanced by a consideration of risk. For example, if a module is relatively small and straight ahead I would think the only documentation needed would be a clear statement of what the module does and a list of tests that will verify its requirements. From that point on I would only expect the programmer to maintain minimal shop standards. The shop I work in is in the process of redoing our software (we develop administrative software for the WA public schools). We have out grown the orginal designs and had gotton ourselves into the position of spending most of our time maintaining the old rather then developing new needed software. Consequently we are now spending millions redoing everything. Had more care been put into good design we might have avoided this expensive project although from what I've heard this problem is common to a lot of companies. I think the key to good software development is not in the coding, but in making sure you are truly meeting your user's needs at every stage of the project and the sooner in the project life cycle these needs are determined the easier it will be to bring the project to a successful conclusion.