Design documentation is not literature; it is a technical tool. The goal is clarity, precision, and usability. Here are 11 rules to guide you when writing a design document.
Rule 1 — Design documentation is not creative writing
This is not schoolwork. Your grammar and style will not be graded.
- Stick to facts.
- Avoid unnecessary adjectives or fancy words.
- Write for clarity, not style.
Rule 2 — A design is not “read,” it is used
A design document is a reference, not a novel.
- Presentation matters less than accuracy.
- Expect readers to jump between sections.
- Keep it practical and functional.
Rule 3 — Use bullets instead of paragraphs
Long paragraphs waste time and create ambiguity.
- Use bullets to present facts clearly.
- Short points reduce misinterpretation.
- Writing is faster, and reviewing is easier.
Rule 4 — Reserve text only for context
Bullets and tables should carry most of the content.
- Use normal paragraphs only in the introduction or when context is essential.
Rule 5 — Use diagrams
A diagram often communicates better than text.
- Diagrams are faster to understand.
- They can replace entire sections of text.
- A visual will stay on desks far longer than written paragraphs.
Rule 6 — Use tables for structured information
Tables are excellent for comparisons, justifications, or inventories.
- Left column: reason or requirement.
- Right column: implementation, explanation, or solution.
- Use tables for equipment lists, feature comparisons, and design decisions.
Rule 7 — Leave adjectives to sales and managers
A design is not a marketing document.
- Avoid subjective language (“fast,” “robust,” “best”).
- Stick to measurable facts and technical reasoning.
Rule 8 — Limit depth to 4 levels
Design documentation should not become endlessly nested.
- High-level (Conceptual) → Low-level (Logical) → Detailed (Physical) → Operational (Implementation and Operational Guidelines, Procedures, Run Books).
- No more than four levels of detail.
- If a section is not more explicit than the previous document, don’t write it.
Rule 9 — Go from general to specific
The design process flows from abstract to concrete.
- Requirements (Design Factors) → High-level design (Conceptual) → Low-level (Logical) → Detailed design (Physical) → Operational guide.
- Each step adds precision and reduces verbosity.
Rule 10 — Use appendices and references
Not everything belongs in the main body.
- If content is useful but not critical, move it to an appendix.
- For external standards, manuals, or detailed procedures—add references instead of duplicating content.
Rule 11 — A big document is a failed document
Size is not quality.
- Long documents are rarely read.
- Conciseness increases value.
- Link to external sources instead of bloating your design.
- Remember: You are not paid per page.
Final Greg's Advice
Do your research, test your assumptions, and always document your design choices.
Keep your design short, precise, and useful—that’s what makes it valuable.
My Approach for any System Design Document
- Design Cover
- Document identifiers
- Contact Matrix
- Role
- Name
- Company
- Phone
- Document Versioning
- Version
- Date
- Author
- What was documented or changed
- Table Of Contents (TOC)
- Interactive Links to Document Sections
- Design Factors
- Project Scope
- Scope
- Target Design Version
- Scope Description
- Business Requirements Analysis
- Business Requirement
- Source (who wants it)
- Target Design Version
- Description
- Fulfillment (how the designer solved it + reference to the specific document section)
- Technical Requirements Analysis
- Technical Requirement
- Source (who wants it)
- Target Design Version
- Description
- Fulfillment (how the designer solved it + reference to the specific document section)
- Functional Requirements Analysis (What the designed system should do. How it should function.)
- Functional Requirement
- Source (who wants it)
- Target Design Version
- Description
- Fulfillment (how the designer solved it + reference to the specific document section)
- Non-Functional Requirements Analysis (How the designed system should behave / typically qualitative parameters of SLA)
- Non-Functional Requirement
- Source (who wants it)
- Target Design Version
- Description
- Fulfillment (how the designer solved it + reference to the specific document section)
- Constraints
- Constraint
- Source (who wants it)
- Target Design Version
- Description
- Assumptions
- Assumption
- Source (who assumes what)
- Description
- Risk Management
- Risk
- Description
- Risk Mitigation
- Conceptual System Architecture
- Logical System Architecture
- Physical System Architecture
- Manageability Architecture
- Recoverability Architecture
- Security Architecture
- Bill of Materials
- Design Log
- Questions and Answers
- Topic
- Comment / Question
- Commentator
- Open Date
- Answer
- Solver
- Close Date
- Status (Open, Answered, On-Hold, etc.)
DESIGN DECISIONS
Through the document, there must be documented DESIGN DECISIONS of particular solutions with clear justifications referencing documented design factors, and document any other potential alternatives, if any. Any INFRASTRUCTURE DESIGN DECISION should consider the following design qualities
- Manageability
- Availability
- Performance
- Recoverability
- Security
- Cost
If you want to get my empty Design Document Template download it here.
No comments:
Post a Comment