Information Technology Reference
In-Depth Information
Chapter 13. Design Documents
Be sincere; be brief; be seated.
—Franklin D. Roosevelt
In this chapter we introduce design documents and discuss their uses and the best practices
surrounding them. Design documents are written descriptions of proposed and completed
projects, big or small. Design documents serve as a roadmap for your projects and docu-
mentation of your accomplishments.
13.1 Design Documents Overview
Design documents are descriptions of proposed or completed projects. They record the
goals, the design itself, alternatives considered, plus other details such as cost, timeline, and
compliance with corporate policies.
Writing out what you are going to do forces you to think through the details. It forces
you to plan. Having a written document can make design collaborative when the document
becomes a communication vehicle for ideas. Written documents mean fewer surprises for
yourteammates,andtheyhelpyoutogetconsensusamongtheteambeforemovingforward.
After the project is completed, the design document serves as an artifact that documents the
work, a reference for the team.
A good design document goes into specific detail about the proposed project or change,
includinginformationonwhychoicesweremade.Forinstance,thedocumentmightcontain
detailed descriptions of algorithms, specific packaging parameters, and locations where
binary files are to be installed, and explain why the config files are going into /etc
instead ofelsewhere. Adesign document about namespace selection, suchasthe design ofa
namespace for server/rack names, will not only describe the naming structure, but also give
the background on why this namespace was chosen and how it does or does not integrate
with existing namespaces.
The document itself is useful for achieving consensus on a project. Sometimes an “ob-
vious” change isn't really so obvious, and people find errors or have questions. As Linus
Torvolds said, “Many eyes make all bugs shallow.”
Search WWH ::




Custom Search