Like I promised, I am going to post more detail. My standard document is based loosely on IEEE Standard 1016-1998, "IEEE Recommended Practice for Software Design Descriptions." A friend who is an IEEE member gave me a copy when he was sent the document as part of a package he ordered. It was not necessary to his job at the time, but was included.
This process often produces a document larger than the final delivery, but I am a subscriber of the old saw "Measure Twice, Cut Once." On my design documents I have three primary parts, the abstract (or executive summary), overview, and details. The abstract is a 2 to 7 paragraph section giving a very high level overview of the application including the desired technology and a description of all primary parts of the application. If more paragraphs are required, add them, but keep in mind that this is just a brief description for non-technical readers of the design document. It is usually written after the requirements are defined and can be used as the basis of refining the requirements. I try to limit this section to a single typewritten page. The overview is a more detailed of the section of the application. In this section each section of the application is described in more detail. If necessary the section is broken down into individual components. The input and output of each section or component are described and any business rules are defined. It is again meant for non-technical readers. It will be the final definition of the requirements. All descriptions should be non-language specific. The application can be written in any language from this description. The final section will be the largest. This defines the actual technical details for each section or component. In some cases it is necessary to introduce language specific restrictions in this section (i.e. OOP vs.Procedural, etc.). I break it down into four main sub-sections a natural language description, the data dictionary (input, output and internal variables), the algorithms, required actions or business rules used, and test cases for each section or component. This entire section is written in natural language, in our case, English. Try not to use jargon or acronyms. However, these are often required for clarity or brevity. If they are used, add a glossary. For database applications I add another section describing the database. The first sub-section describes the schema. The next describes any queries, user defined functions, stored procedures, views, etc. These define the input, output and algorithms or business rules. The final subsection describes any further business rules or database interactions. The description of this sub-section is left kind of nebulous as it is where anything not described with the database section is described. In the case of a complex application I also add a glossary and appendices. The appendices define anything not commonly known to the design team like algorithms for uncommon mathematical processes (i.e. a Poisson distribution or specific random number generator to be used). I also define programming techniques or architecture to be used like and n-Tier architecture or the FuseBox framework. These are not necessary for the actually description, but are added to give the non-technical readers a base to understand any discussions in which they may be involved. I hope this helps. I'll be glad to help if you have further questions. Russel On 10/6/06, Ian Skinner <[EMAIL PROTECTED]> wrote: > > Russel > > Thanks a lot. > > > -------------- > Ian Skinner > Web Programmer > BloodSource > www.BloodSource.org > Sacramento, CA > > --------- > | 1 | | > --------- Binary Soduko > | | | > --------- > > "C code. C code run. Run code run. Please!" > - Cynthia Dunning > > Confidentiality Notice: This message including any > attachments is for the sole use of the intended > recipient(s) and may contain confidential and privileged > information. Any unauthorized review, use, disclosure or > distribution is prohibited. If you are not the > intended recipient, please contact the sender and > delete any copies of this message. > > > > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| Introducing the Fusion Authority Quarterly Update. 80 pages of hard-hitting, up-to-date ColdFusion information by your peers, delivered to your door four times a year. http://www.fusionauthority.com/quarterly Archive: http://www.houseoffusion.com/groups/CF-Community/message.cfm/messageid:217093 Subscription: http://www.houseoffusion.com/groups/CF-Community/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=11502.10531.5
