Design Document Readability: Core Principles, Key Points, and Best Practices

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

1. Why write design documents and emphasize their readability (click to read)

2. Core principles of design documents: the 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

Writing style’s three elements

Technical writing for design documents also emphasizes three elements:

Clarity

Conciseness

Elegance

The detailed style of technical writing will be introduced in later articles (if any) and can be referenced in the bibliography.

Four key points of design

The following are several points to note when designing systems and writing design documents. They are not exhaustive; more detailed explanations will appear in subsequent articles.

3.1 Every architectural issue is a trade‑off.

Everything in software architecture is a trade‑off.

In software design, no dimension is absolutely better or worse. Each design decision must consider many conflicting factors.

For example, scalability vs. efficiency, long‑term performance vs. short‑term gains, scaling improves efficiency but reduces flexibility. “High cohesion, low coupling” facilitates iteration but raises short‑term development cost. NoSQL is faster than SQL but sacrifices many features.

If a design decision appears to have no trade‑off, it is usually because the trade‑off has not yet been identified.

3.2 “Why” is more important than “how”.

3.3 Consider the time dimension

Software Engineering = Coding * Time.

When making design trade‑offs, the time dimension must not be ignored; designs should consider more than just the final state of a single phase. Design should consider:

Maintainability and scalability

Implementation path

Future plans

3.4 Avoid over‑design

At the start of design, define the problem scope. A well‑defined problem is a prerequisite for a good design.

Do not worship design models, patterns, or X‑driven design; they are tools, not rules.

Do not create problems to solve problems.

Do not use complex designs to showcase difficulty; a hard problem may have a simple solution.

Do not worry excessively that the design will be quickly obsolete.

Preserve extensibility, but do not waste effort on unknown future extensions.

Typical example of over‑design:

https://github.com/EnterpriseQualityCoding/FizzBuzzEnterpriseEdition

Conclusion

The most important thing is to know how to design and know what you are designing.

The Dunning‑Kruger effect tells us that this may not be obvious.

Promotional Note: Teacher Qiao Liang is launching a video course “Continuous Deployment Bootcamp (Python Edition)” with a limited‑time discount. The course helps improve software development efficiency, quality, and deployment reliability through theory and hands‑on practice, covering build‑test‑deploy pipelines, monitoring, gradual feature rollout, and database schema changes.