Best Practices for Writing Readable Design Documents

This series of three articles explains how to make design documents more readable, starting with why documentation matters and emphasizing clarity.

1. Word Choice – Use concise, accurate, and plain language; employ common technical terms correctly, provide English equivalents when needed, and avoid obscure abbreviations.

2. Avoid Excessive Adverbs – Phrases like “very important” add little value compared to simply “important”.

3. Use Data – Replace vague claims with concrete numbers (e.g., “performance improved by 42%”) to increase credibility.

4. Avoid Boilerplate – Eliminate overly formal or archaic expressions; prefer short, direct sentences.

5. Sentence Construction – Prefer short sentences over complex, multi‑clause structures; remove unnecessary modifiers and softening clauses.

6. Tone – Keep a calm, professional tone; avoid colloquialisms, filler words, and exclamation marks; use bold or italics for emphasis instead.

7. Accurate Description – Stick to objective facts without injecting personal opinions.

Paragraphs – Keep paragraphs short (no more than eight sentences), start each with a clear topic sentence, and ensure all sentences support that topic.

Lists – Use bullet points for unordered lists and numbered items for ordered sequences; explain list usage in a later article.

Structure – Follow a template that includes sections such as Goal, Background, Overall Design, Detailed Design, Alternatives Considered, Cross‑Concerns (infrastructure, scalability, security, data integrity, latency, redundancy, stability, external dependencies), Implementation Plan, and Future Plan.

Each section should be self‑contained, providing enough context for readers to understand without external references.

“系统形式问题就是下面这样一个问题：怎样把各种不同的对象种类安排在一个系统中，以使较高的对象种类总能从较低的对象种类构造出来，也就是说前者可还原为后者。为了解决这个问题，我们必须从其相互可还原性来研究各种不同的对象种类。” – Rudolf Carnap

The article also supplies a design‑doc template, guidance on headings hierarchy, consistent typography, limited color usage, and references to further reading on technical writing and software architecture.