Writing a Good Software Design Document

2005

By Ofer Faigon
www.bitFormation.com

Articles

Over the years I've read hundreds of design documents and consequently formulated an opinion as to what makes an excellent design paper. This article is an attempt to list both good and bad features I've seen in design documents and to briefly describe the effect of each of these features.

[Note: The article was written bearing in mind medium sized projects in commercial companies. A different setting of software development may require variations.]



The functions of a design document

Ask a fellow programmer what the purpose of writing a design document is, and the most likely answer you are going to get is "to let the programmers know what code to write". This is true, but there are several other reasons for writing this document, and they are by no means less important.

  • Communicating your design to others:
    • To implementers.
      Goes without saying. The programmers do have to know what code to write.

      » In order to help them write efficiently, the design should be clear, complete and well defined.

    • To fellow designers.
      Many designs, especially the ones describing larger systems, are given to fellow software designers to read and comment. They will ask questions, find bugs and mistakes and suggest improvements. This interaction is very important from the company's point of view - it will produce a much better design and save a lot of time and money in the long run.

      » In order to optimize this interaction, you should specify the decisions you made in building your design and explain the reasons behind each one of them.

    • To successors.
      It is most likely that at some point in time you will move on to other projects and let someone else take over and be in charge of your former design. This person will extend it, or modify it, as the requirements change and the system evolves. Your original design document will then be an invaluable resource of your design philosophy, intent and assumptions. Your successor will really need this insight in order to be able to expand the design without breaking it.

      » Thoroughly explain your design philosophy and intentions.

    • To managers.
      You probably have to report to someone. That someone needs to see the results of your work, either to evaluate your progress, or to gain a better understanding of the design and the resources it will require when implemented, or even to get an indication of how good you are at what you do.

      » Form carries just as much weight as content. The document should be carefully arranged and edited so that it would be aesthetic to look at. Additionally, the reader should be able to derive time estimates from the content.

    • To guests.
      New employees usually go through a period of training during which they are given various internal documents to read in order to familiarize themselves with the company products. Your software design document is almost surely to be one of these documents.
      Investors sometimes come to inspect the company. One of the things they will want to see is the software design document.
      During the initial stages of the project there is no finished product to show potential customers. Instead, it may be necessary to convince them that the future product is a viable solution to their problem. One of the means your company might use to do so is your design document.

      » The document should be presentable. It should give the various readers a general view of the purposes and context of the project, taking into account the probability that not all readers will know in advance what the project is all about.

  • Processing your ideas and converting them into a solid design
    I find this to be a central goal in writing the document. When thoughts are put into writing, it is much harder to overlook problematic issues. This is particularly true if you do your best to anticipate every possible question and objection your readers may have.

  • Allowing for increased accuracy in time estimates
    At the beginning of a project, one of the first steps is to estimate the amount of work involved. This is a very rough estimate, and it is based on previous experiences with projects of a similar size. As such, it is bound to be off by a factor of two or more. As the work progresses, there is need to come up with more accurate estimates, and the best tool for this is a detailed design. Once you have the design document and you iron out all the problems and details you could think of without actually writing the code, you can give a fairly accurate estimate for every module and function in the design. Adding these up and allowing some margin for unforeseen problems will give you a rather accurate measure of the work involved.

    » The document should reflect the size and complexity of every part of the software. It should also mention factors that may affect the duration of the coding phase, such as the use of new technologies, languages, tools or environments, or the requirement for a special skill set, etc.

  • Allowing for content adjustments
    In the course of virtually any software project, a moment arrives when it becomes clear that the required feature set cannot be developed within the given time frame. Normally, under these circumstances, the less important features are identified and removed in order to meet the (possibly extended) time frame. In some companies, this may be done without referring to the design document while in others the design document will be a major reference for this adjustment.

    » The design document must elaborate on the dependencies among the various coding phases, and should attach a concrete cost to each of the project requirements.



What to include in it

At the end of this article you will find the template of a generic design document along with notes explaining what each section should contain. In addition to using this template and modifying it to suit your own needs, you should pay attention to the following details:

  • A descriptive title. 'Medusa High Level Design' is much better than 'Medusa'. Remember that the readers will probably have several documents to read, and they need to have an idea what kind of document this is.

  • A separate title page, formatted according to your company's standards. This usually means using a very large font for the title.

  • Last modification date and time. It is surprising to see how many hours are wasted in meetings when several people look at different versions of the same document. Put the date on the cover page, or in the footer of every page. Make use of your word processor auto- update feature to ensure that the date is always correct.

  • Section numbers. Absence of section numbers is another cause for wasted meeting time. If your sections are long, it might be a good idea to have line numbers printed on each page so that the people in the meeting will immediately be synchronized. Here, too, your word processor automatic numbering feature is invaluable.

  • Page numbers. The 3rd cause for wasted time during meetings is the absence of page numbers. Page numbering will also help locate defective copies with missing or mixed up pages.

  • A table of contents. If you use your word processor automatic section numbering feature, it is very likely that you will not need to work hard in order to add a table of contents as well. Every now and again it can make someone's life easier.

  • Block diagrams. Include at least one block diagram to demonstrate how the major modules relate to one another. In large systems you will probably want an additional block diagram to show the internal structure of each module. It is often easy to present the modules, the threads, the control flow and the data flow in the same diagram, but some systems are complex enough to require several diagrams to show all of these. If the system is comprised of several processes, try to convey which of the processes must run on the same machine and which ones can be remote. Furthermore, illustrate which ones may have multiple instances running concurrently.

  • Explain terms and acronyms when you first introduce them. Although most of your audience is familiar with these terms and acronyms, you must take into account those readers who do not share the same technical/professional background, such as investors, new employees, guests, etc. If you feel that explanations in the body of the text may be distracting, create a separate glossary section for them.

  • Your company may have a standard document template with some administrative noise. This may include things like a revision history, the intended audience, a list of related documents, pre- requisites, purpose, copyright notice, classification, some legal statements, typographical conventions, aesthetic page frames, version number, dedications, thanks, disclaimer, stamps like 'For Internal Use Only', 'Confidential' or 'Draft'...

  • Trivial, but often neglected: Use a consistent notation, a consistent terminology, different fonts for different purposes, white space between paragraphs and between sections, indentation. If chapters are longer than 1-2 pages each, then insert a page break before the beginning of a new chapter. If you are not experienced with font selection, it is always a safe bet to use Helvetica (Arial) for titles and Times (Times New Roman) for text.



Techniques

Over the years I've learned and used several techniques and tricks to improve my design documents:

  • Prepare a skeleton in advance - a document containing only section titles. You can copy the example given below and edit it to fit your project, or use an existing document after you've deleted the text. This will help you trace with ease any forgotten sections.

  • Imagine you are writing the design for people who will read it in your absence. Try to anticipate their questions, trivial as well as prominent, and make certain your answers are embedded in the text.

  • Once you've written the document, go over it with a fine toothcomb. Assume the role of a non-compromising critic, and look for faults and counter arguments. At the end of this review your text should make a convincing case for your design decisions.

  • When you feel you have an adequate version, let other people (preferably from different backgrounds) read it and ask you questions. Every question may suggest an unclear or missing explanation. Ask for comments and suggestions, and do not reject any idea before you put it to careful examination.



What to avoid

  • Avoid using lists of cryptic nouns. As tempting as it may be to quickly jot down your ideas, a design document written in shorthand will not convey your thoughts and intentions to the readers. Instead, it will cause misconceptions and misinterpretations.

  • Do not make up too many terminological innovations (particularly, abbreviated module names) to use in your document. The average reader will soon feel lost and unable to follow your ideas.

  • When your text relies on other documents, try not to assume that the readers are fully informed and in complete understanding (and recollection) of these documents. Write a few sentences to summarize each document you rely on for the benefit of your readers.

  • Avoid using cryptic references known only to a limited number of people. Supply an explanation, however brief, so that the interested reader may look up each reference elsewhere.



A Design Document Template

The following is a generic design template suited to the requirements of a medium sized software project. However, since every system is different, your particular design may need a distinct list of sections.