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

13.3 Template
Givingsomeoneatemplatetofilloutguidesthatpersonthroughtheprocessofcreatinghis
or her own design documents better than a step-by-step guide or a sample document could
ever do. The template should include all headings that the final document should have,
even optional ones. The template can be annotated with a description of what is expected
in each section as well as helpful hints and tips. These annotations should be in a different
font or color and are usually deleted as the user fills out the template.
Anexampletemplatecanbefoundin SectionD.1 of AppendixD . Useitasthebasisfor
your organization's template.
The template should be easy to find. When the template is introduced, everyone should
be notified that it exists and provided with a link to where the template can be found. The
link should appear in other places, such at the table of contents of the design document
archive or another place that people frequently see. Make sure the template shows up in
intranet searches.
The template should be available in all the formats that users will be using, or any
format with which they feel comfortable. If people use MS-Word, HTML, MarkDown
(a wiki format), or OpenOffice/LibreOffice, provide the template in all of those formats.
Providing it in your favorite format only and assuming everyone else can improvise is not
making it easy for others to adopt the system.
It can also be useful to provide a short template and a long template. The short template
might be used for initial proposals and small projects. The long template might be used for
complex projects or formal proposals.
The template should also be easy to use. Anytime you see someone not using the tem-
plate is an opportunity to debug the problem. Ask them, in a nonconfrontational way, why
the template wasn't used. For example, tell them that you're looking for feedback about
how to get more people to adopt the template and ask what you could do to have made it
easier for them to use it. If they say they couldn't find the template, ask where they looked
for it and make sure all those places are updated to include links.
13.4 Document Archive
There should be a single repository for all design documents. Generally this can be as
simple as a list of documents, each linked to the document itself. For the document archive
to be useful to readers, it should be easy for people to find the documents that they are
looking for. A simple search mechanism can be useful, although people will generally be
happy if there is one page that lists the titles of all documents and that page itself can be
searched.