Path: utzoo!attcan!uunet!cs.utexas.edu!news-server.csri.toronto.edu!helios.physics.utoronto.ca!ists!yunexus!davecb From: davecb@yunexus.YorkU.CA (David Collier-Brown) Newsgroups: comp.software-eng Subject: Re: Amount of Design Documentation Message-ID: <13581@yunexus.YorkU.CA> Date: 7 Aug 90 12:50:13 GMT References: <2314@polari.UUCP> Organization: York U. Computing Services Lines: 43 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. Alas, that's ALL low-level. The first makes a good technical paper, of interest to people working on the software, and the second makes a good interface (Ada) or .h (C) file. But first you need a statement of what it's going to do, for whom, and why. Check out the Project Athena Technical Plan for an example: various parts are obtainable via ftp. My preferred approach is to write the user manual first, and then get it checked by 1) the marketdroids, to see if i **have** a real product (carefully ignoring their particular suggestions (:-)) 2) the (lonely) ergonomist, to see if I have a usable product, 3) our RFP-response manager to see if it meets what the customers have been asking for (nb: NOT the marketing deptarement, I want the raw data). 4) a customer volunteer, so they know what we're proposing and have a chance to scream. Then I write a features list, order it from "in first release" to "never" by clustering capabilities, define the primitives I need to have to provide them, and write my Technical Plan, which some unlucky manager gets to sign off on. --dave (for small projects, this can be "write man page. write code") c-b -- David Collier-Brown, | davecb@Nexus.YorkU.CA, ...!yunexus!davecb or 72 Abitibi Ave., | {toronto area...}lethe!dave Willowdale, Ontario, | "And the next 8 man-months came up like CANADA. 416-223-8968 | thunder across the bay" --david kipling