Why Write Design Documents and Emphasize Their Readability

This series of articles is divided into three parts that introduce the readability of design documents.

1. Why write design documents and stress their readability

2. Core principles of design documents: three writing elements and four key points

3. Best practices for design documents

If you cannot write clearly, you may not be as smart as you think.

- Kurt Vonnegut Jr

What is a design document?

A design document is a systematic description of a solution to a technical problem.

Why write a design document?

Is the software being developed large enough to justify the extra time spent writing and reviewing a design document to reduce failure risk?

If senior engineers cannot ensure code review for every piece of code, would involving them in design review yield higher returns?

When a design decision is vague or controversial, is it necessary to reach organizational consensus through a design document?

Should a design document highlight cross‑cutting concerns such as privacy, security, or logging?

Is it necessary to write a document that provides a global analysis of legacy system design issues?

If the answer to any of the above questions is “yes,” you should consider solving the problem by writing a design document.

Through a design document we can:

Detect design problems early when iteration costs are low.

Shift design and cost left, enabling fast failure.

Achieve team consensus on the design.

Make trade‑offs explicit, helping readers understand and accept decisions.

Spread senior engineers’ experience to the whole team, fostering growth.

Provide a learning resource for junior engineers.

Allow reviewers to give feedback on junior engineers’ designs.

Establish a consistent way of documenting software design and preserve technical knowledge.

If the solution is crystal‑clear and involves no trade‑offs, the design document can be omitted and the solution implemented directly.

Why emphasize readability?

3.1 Design documents have the highest read‑write ratio (ROI). The reading time of a design document far exceeds the writing time, so investing in readability is worthwhile.

3.2 Design documents are not literary works. Their purpose is communication, not self‑expression; focus on clear, concise expression rather than prose.

3.3 Write for the reader. Understand who your readers are; they are often many engineers with varying familiarity with the system.

When the audience is broader, the document needs more background, fewer internal terms, and more explanation of design rationale and trade‑offs rather than implementation details.

3.4 Design document readability vs. code readability. Both share common aspects: they should highlight non‑obvious information, there is no perfect answer, readability is subjective, and the goal is to make the document easier for most readers.

Improving documentation and code quality is a habit; methods include reading excellent design docs, conducting design‑doc and code reviews, and writing, revising, and rewriting frequently.

Story‑telling structure for design documents (OCAR)

Opening : background introduction.

Challenge : the problem to solve.

Action : the experiment/design/implementation.

Resolution : the outcome.

Mapping each part of a typical design‑doc structure to OCAR helps tell a coherent story.