Architecture Docs Writer

Writing Architecture Documentation

Architecture docs in this repo serve two audiences: team members working on the system (need precise reference material) and team members seeking context (need an accessible narrative). The doc must work for both without requiring prior project context.

Before writing

1. Read at least two sibling docs in the same directory (e.g., other subsystem docs under docs/architecture docs/subsystems/). Calibrate your voice, structure, and level of detail to match them.
2. Read the ADRs you'll reference. Don't just link to them — understand them well enough to summarize the key idea inline, so the reader doesn't have to follow the link to understand the doc.

Voice and framing

Write about the system, not the project. These docs describe the intended system as far as we know it. They are not project retrospectives, sprint summaries, or PoC reports.

• State facts: "The execution pipeline generalizes across families" — not "The PoC validated that the execution pipeline generalizes"
• No transient project references: avoid "workstream", "PoC", "sprint", "milestone", "being validated", "current effort"
• No product comparisons: don't reference other products or prior versions. Describe what the system is, not what it improves upon.
• Non-goals are architectural boundaries, not "not yet done" items. No (current) qualifiers.

Write for a developer without prior context. Imagine someone joining the team and reading this doc as their first exposure to this part of the system.

• Explain why before what. Before introducing a concept like model ownership, explain the problem it solves: "In SQL, related data lives in separate tables and is joined at query time. In MongoDB, the idiomatic pattern is to store related data inside the parent document."
• Let ideas breathe. Don't compress three concepts into one sentence. If a sentence requires the reader to already understand three things to parse it, break it apart.
• Use concrete examples — code snippets, JSON fragments, "a developer writing X gets Y under the hood." Abstract descriptions are hard to pin understanding to.

Structure

Lead with a grounding example. Put a concrete, complete code snippet, JSON example, or diagram near the top of the document — right after the overview — so the reader has a visual reference to pin their understanding to as they read. Abstract explanations are much easier to follow when the reader can refer back to something tangible. Annotate the example with brief callouts that preview the key concepts ("notice that storage: {} means this model is embedded"). The detailed sections that follow can then elaborate on what the reader has already seen.

Articulate design principles early. If the subsystem's design is shaped by a set of principles or invariants, state them explicitly after the grounding example and before the detailed sections. This gives the reader the reasoning framework they need to understand why specific decisions were made. Each principle should be one or two sentences of plain language, not jargon. Later sections can reference the principles by number (e.g., "see design principle #5") to connect specific decisions back to their rationale.

Narrative flow. Guide the reader from one concept to the next. Don't list a set of problems and then separately list a set of solutions — pair each problem with its solution so the reader builds understanding incrementally.

Overview section. Open with plain language explaining what this part of the system is and why it exists. The first sentence should be immediately understandable by any engineer. Save technical details for later sections.