Design Documents - The Practice of Cloud System Administration - page 275

simple email by a year's worth of changes and you have an entire set of information that is
basically inaccessible to the team.
Don't say it; write it down. Procedures, designs, and wisdom count only when they are
written down. People can't refer to your words unless they are in writing. In that regard,
email is speech, not writing ( Hickstein 2007 ) .
13.2 Design Document Anatomy
A design document has many parts. They start with the highest-level information, getting
more detailed as the document proceeds. We aid reader comprehension by standardizing
the format, headings, and order of these parts.
Appendix D includes an example of a complete design document in Section D.2 . A
sample template appears in Section D.1 .
The sections are:
Title: The title of the document.
Date: The date of the last revision. Author(s)/Reviewer(s)/Approver(s):
Reviewers are people whose feedback is requested. Approvers are people who must ap-
prove the document.
Revision Number: Documents should have revisions numbered like software releases.
Status: Status can be draft, in review, approved, or in progress. Some organizations
have fewer or more categories.
Executive Summary: A two- to four-sentence summary of the project that contains the
major goal of the project and how it is to be achieved.
Goals (Alternatively, “In Scope”): What is to be achieved by the project, typically
presented as a bullet list. Include non-tangible, process goals such as standardization or
metrics achievements. It is important to look at your goals and cross-check each one to see
thatyourdesigndocumentaddresseseachgoal.Insomeorganizations,eachgoalisgivena
numberandthegoalsarereferredtobynumberthroughoutthedocument,witheachdesign
description citing the appropriate goals.
Non-goals (Alternatively, “Out of Scope”): A bullet list is typically used to present this
information. A list of non-goals should explicitly identify what is not included in the scope
forthisproject.Thisheadsoffreviewcommentslike“Thisprojectdoesn'tsolveXYZ”be-
cause we are communicating here that this project is not intended to solve XYZ.
Background: What a typical reader needs to know to be able to understand the design.
This section might provide a brief history of how we got here. Identify any acronyms or
unusualterminologyused.Documentanypreviousdecisionsmadethathaveplacedlimita-