|
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.
|
 |
Contact