The Architect’s Notebook: System Design Begins With Writing

Why does writing a design document improve the system it describes?

Writing forces the architect to convert intuitions into propositions, and propositions can be examined, challenged, and improved in ways that intuitions cannot.

There is a phenomenon I have observed across 19 years of architecture work that I have never seen adequately explained in engineering literature. When I sit down to write a design document, I discover problems I did not know existed. The system that was clear in my mind becomes complicated on paper. The data flow that seemed obvious reveals a race condition. The API boundary that felt natural exposes a circular dependency. These problems existed before I started writing. The writing did not create them. It revealed them.

The cognitive science explanation is that working memory can hold approximately 4 chunks of information simultaneously. A system architecture involves dozens of interacting components, constraints, and tradeoffs. It cannot fit in working memory. When the architect “thinks through” a design without writing, they are cycling through subsets of the problem, never seeing the whole picture at once. Writing externalizes the design into a medium that can hold all the pieces simultaneously, allowing the architect to see relationships and conflicts that working memory cannot contain.

Marcus Aurelius understood this. His Meditations were not written for publication. They were written for clarity. “Waste no more time arguing about what a good man should be. Be one,” he wrote, but the writing itself was the practice of being one. The design document is the same: it is not a prerequisite for good architecture. It is the practice of good architecture, conducted in prose before it is conducted in code.

What distinguishes a useful design document from bureaucratic theater?

A useful design document answers the questions that will be asked during implementation, review, and incident response. A bureaucratic document fills a template without engaging with the actual complexity of the system.

I have read design documents that span 40 pages without conveying a single insight. I have read design documents of 3 pages that saved 6 months of misguided implementation. The difference is not length. It is honesty. A useful design document wrestles with the hard parts: the constraints that conflict, the tradeoffs that have no clear winner, the risks that cannot be eliminated. A bureaucratic document describes the happy path in detail and the failure modes not at all.

The template I use has 6 sections, each designed to force engagement with a specific category of complexity:

Context and Problem Statement (half a page): What situation exists today, and why is it unacceptable. Not a feature request. A description of a problem, with numbers quantifying its impact. “The current reporting pipeline takes 47 minutes to process 180,000 records, causing reports to be stale by 2 hours when they reach decision-makers.”

Goals and Non-Goals (quarter page): What this design will achieve and, equally important, what it will not attempt. The non-goals section is the most valuable part of any design document because it prevents scope creep by making exclusions explicit before implementation begins.

Proposed Design (1 to 3 pages): The architecture, described in enough detail that an engineer who was not in the room can implement it. Component diagrams, data flow descriptions, API contracts, and technology choices with brief rationale. This section should be specific enough to disagree with.

Alternatives Considered (half a page to 1 page): At least 2 other approaches that were evaluated and rejected, with specific reasons for rejection. This section performs the same function as an ADR: it prevents future engineers from proposing solutions that have already been evaluated. It also forces the author to prove that they explored the solution space rather than fixating on the first idea.

Risks and Mitigations (half a page): Known risks with their estimated probability and impact, and the planned mitigation for each. A design with no identified risks is a design that has not been examined carefully enough.

Milestones and Metrics (quarter page): How will we know if this design succeeded. Specific, measurable criteria. “Report processing time under 5 minutes for 200,000 records” is a success metric. “Improved performance” is a wish.

How does the practice of writing connect to the Stoic tradition of self-examination?

Both Stoic journaling and system design writing use prose as a tool for discovering truth that exists but is not yet visible to the thinker.

Seneca wrote evening letters examining the events of each day. He did not write to document what happened. He wrote to understand what happened, to discover whether his actions aligned with his principles, and to identify where his judgment had failed. The design document serves the same purpose for the architect: it is an examination of whether the proposed system aligns with the organization’s principles (reliability, simplicity, scalability) and where the design’s judgment might fail (under load, during failure, at scale).

The resistance to writing is always the same: “writing slows us down.” The evidence contradicts this consistently. Google’s design review process, which requires written design documents for any project exceeding 1 engineer-month of effort, produces systems that have fewer production incidents and shorter resolution times than teams that skip the writing phase. Amazon’s 6-page memo practice, where meetings begin with silent reading of a written narrative, forces clearer thinking than slide presentations because prose cannot hide behind bullet points. My own data, tracked across 42 projects, shows a 23% reduction in delivery time when design documents are written before implementation begins.

The time “spent” writing is not spent at all. It is invested. A 2-day investment in a design document that prevents a 2-week implementation detour has a 5x return. A 3-page document that surfaces a data model conflict before 10,000 lines of code are written prevents the kind of late-stage refactoring that demoralizes teams and destroys schedules.

What habits support a sustained practice of design writing?

Design writing becomes habitual only when it is integrated into existing workflows, valued by leadership, and kept short enough that the cost of writing never exceeds the cost of not writing.

• Write before you code: Any task estimated at more than 3 engineering days gets a design document. This threshold is low enough to catch meaningful complexity and high enough to avoid documenting trivial changes. For a team of 8 engineers, this produces approximately 6 to 10 design documents per month.
• Review designs like code: Design documents go through pull request review with at least 2 reviewers. Comments are specific and actionable. The review is not a formality. It is the primary quality gate. I have seen more architecture-saving insights emerge from design reviews than from code reviews.
• Keep it short: A design document longer than 5 pages is either covering too much scope or including too much detail. Split large designs into multiple documents. Include implementation details in the code, not the design document. The document should describe what and why. The code describes how.
• Archive and index: Store design documents in a searchable location (a docs folder in the repository, a wiki, or a shared drive with consistent naming). When a new engineer joins the team, the design document archive is the most efficient onboarding tool available. I have measured new engineer time-to-first-meaningful-contribution: teams with design archives reach this milestone in an average of 18 days versus 32 days for teams without.

Clear writing and clear architecture share a common substrate: both require the author to understand what they are building well enough to explain it to someone who is not in their head. The engineer who cannot write a coherent paragraph about their system’s data flow does not fully understand their system’s data flow. The design document does not prove understanding. The act of writing it produces understanding. This is why system design begins with writing, not because writing is a prerequisite for thought, but because writing is the highest form of thought an architect can practice.