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

Case Study: Working Backward at Amazon
Amazon encourages engineers to start by describing what the customer will see,
then work backward to build the design. Engineers start by writing the press re-
lease that they would like to see announce the product. They design the marketing
materials describing how the customer will benefit from the product, identifying
thefeatures,andansweringFAQs.Thisdevelopsthevisionofwhatwillbecreated.
Only after this work is finished is the design created that will achieve the vision.
The process is fully described in Black ( 2009 ).
13.1.1 Documenting Changes and Rationale
Design documents can also be used to describe changes instead of projects. A short design
document is a good format to get consensus on a small change such as a new new router
configuration, a plan to adopt a new feature of a configuration management system, or a
new naming scheme for a file hierarchy.
A design document is created to capture the specifics of the proposed change, and used
as a sounding board for team input. If a formal change control process is in place, the same
document can be included in the change request.
13.1.2 Documentation as a Repository of Past Decisions
An archive of design documents becomes a reference for anyone needing to understand
how things work or how things got the way they are. New team members can come up to
speed more quickly if there is documentation they can study. Existing team members find
itusefultohaveareferencewhentheyneedaquickrefresheronaparticularsubject.When
collaborating with other teams, it is useful, and looks much more professional, to point
people to documents rather than to explain things extemporaneously.
When knowledge can be conveyed without requiring personal interaction with an ex-
pert, it makes the team more efficient and effective. Teams can grow faster, other people
canadoptourservice morerapidly,andwehavethefreedom totransfer between teams be-
cause knowledge is not locked to one person.
Design documents convey not just the design, but also goals and inspirations. Since
people will refer to design documents for a long time, they are a good place to store back-
ground and context.
Often teams retain the history of decisions in their email archive. The problem is that
email is, by nature, sequestered in a person's mailbox. New team members cannot find
those emails, nor will they appear in a search of a documents archive. Multiply that one