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

your team use them. Another way to start using design documents is to make them a re-
quirementforcertainapprovalprocesses,suchasbudgetreview,securityorfirewallreview
boards, or change control. Avoid requiring blind adherence to the template format as a re-
quirement for approvals. Content is more important than presentation.
When they see that the template is easy to use, team members will start adopting it for
other projects.
Usethetemplate yourself.Ifthetemplate isnotbenefitingyoupersonally,itisprobably
not beneficial to others. Using it also helps spot problems that often can be fixed as easily
as updating the template. When Tom joined Stack Exchange, one of the first things he did
was create a design document template and put it on the department wiki. He used it for
two proposals before mentioning it, revising and perfecting the template each time he used
it. Only after it had been used a few times did he mention the template to his teammates.
Soon others were using it, too.
13.7 Summary
Adesign document serves as a project roadmap and documentation. Its primary function is
to describe a project, but it also communicates key aspects of the project (who, what, why,
when, and how) to the team. Design documents are useful for change control as well as
forprojectspecifications.Gooddesigndocumentswillcapturenotonlythedecisionsmade
but also the reasoning behind the decisions.
Adopting design documents can pose cultural challenges for a team. Start with a good
template in an easy-to-find location, made available in the formats your team uses for doc-
uments.Createacentralrepositoryfordesigndocuments,organizedinorderofmostrecent
updates. Make it easy to add a design document to the repository's main directory page.
Approvalsarepartofgooddesigndocumentculture.Createadraftdocumentandsolicit
comments from some portion of the team. For simple workflows, email is sufficient to
pass the document for review. For more formal workflows, there may be mandatory re-
view boards or multiple approval steps. In all workflows, the version number of the design
document is updated each time review comments are added to the document. Ideally, the
document repository's main page will also be updated as revisions occur.
Templates should contain the major points of who, what, why, when, and how. Shorter
templatesmaybeusedforsmallorinformalprojects,withlarger,morecompletetemplates
being preferred for complex or formal projects. At a minimum, the template should have
title, date, author(s), revision number, status, executive summary, goals, high-level design,
anddetaileddesignsections.Alternativeoroptionalsectionscanbeaddedtocustomizethe
template based on the needs of your organization.