Architecture Documentation#

If the architecture isn’t written down, it exists only in one person’s head — and even there, it degrades over time. Memory is unreliable, especially for design decisions. Six months after a project, the reasoning behind a particular signal conditioning topology, a two-stage power supply, or the choice of 3.3V over 1.8V for the digital section will be lost. Documentation captures these decisions while they’re still fresh.

Why Document Architecture?#

The schematic captures what the circuit is. Architecture documentation captures why it is that way. The distinction matters because:

• Schematics don’t explain alternatives. The schematic shows a buck converter. It doesn’t show that a boost converter was considered, an LDO evaluated, and the buck chosen because the dropout was too high for the LDO and the voltage direction was wrong for the boost.
• Schematics don’t explain constraints. The schematic shows a four-layer board. It doesn’t explain that four layers were needed because the ADC required a continuous ground plane under its analog inputs, which couldn’t be achieved on two layers.
• Schematics don’t explain tradeoffs. The schematic shows a 100 kHz switching frequency. It doesn’t explain that 500 kHz would have been smaller but violated the EMC budget, while 50 kHz would have required a larger inductor.

Architecture documentation fills these gaps. It’s the narrative that makes the schematic comprehensible to someone who wasn’t in the designer’s head when the decisions were made.

Minimum Viable Documentation#

Documentation doesn’t have to be formal or exhaustive to be useful. A project with no documentation at all is a project that can’t be understood, maintained, or improved by anyone — including the person who designed it. But a project with excessive documentation that nobody reads is also a failure.

The minimum set that has proven consistently valuable:

Block Diagram#

The system-level block diagram (see Block Diagrams as Thinking Tools) is the single most important architecture document. It shows:

• Major functional blocks and their relationships
• Signal flow direction and type
• Power architecture and voltage domains
• External interfaces and connectors
• Key parameters (signal levels, data rates, power consumption)

This is the document that answers “what does this system do and how is it organized?” in one view.

Interface Definitions#

A list of the interfaces between blocks (see Interfaces & Boundaries) with their key parameters:

This table might be informal — a text file, a section of a project notebook, or annotations on the block diagram. The format doesn’t matter; the information does.

Design Decisions and Rationale#

The most frequently forgotten and most valuable documentation: why was this decision made?

A design decision record doesn’t need a formal template. A simple entry works:

Decision: Use a TLV1117-33 LDO instead of a switching regulator for the analog supply.

Context: The analog section draws 30 mA max and is sensitive to supply ripple. The input voltage is 5V USB.

Alternatives considered:

• Switching regulator: higher efficiency but introduces switching ripple (10-50 mV typical) that would require additional filtering.
• Ferrite bead + capacitor filter from the 3.3V digital supply: simpler but couples digital noise to the analog section.

Rationale: The 1.7V dropout at 30 mA dissipates 51 mW, which is thermally insignificant. The LDO provides inherently low output noise (< 1 mV) without additional filtering. The efficiency penalty is acceptable given the USB power source.

This takes five minutes to write and saves hours of “why was this done?” questioning later. It also prevents the next revision from “improving” the power supply by replacing the LDO with a switching regulator, not realizing the LDO was chosen specifically for its noise performance.

Living Documents vs Snapshots#

There are two approaches to documentation maintenance, and they serve different purposes:

Living documents are updated as the design evolves. The block diagram reflects the current design, the decision records include the latest changes, and the interface table matches the current schematic. Living documents are useful for active projects that are being modified.

Snapshots capture the state of the design at a specific point in time — typically at each PCB revision. “Rev 1 architecture” is a frozen document that records what was designed and why. When rev 2 is started, a new snapshot captures the updated architecture.

For personal projects, a practical approach is: maintain a living block diagram and keep a running list of design decisions. At each board fabrication, save a snapshot — a copy of all documentation with the revision label. This provides both a current view and a historical record.

Documentation Tools#

The best documentation tool is the one that actually gets used. Some options:

Plain text and markdown. Simple, version-controllable, searchable, and tool-independent. A design-notes.md file in the project repository captures decisions in a format that survives any tool change. This is what I use most.

Schematic annotations. Many EDA tools allow text notes on schematic sheets. Putting design rationale directly on the schematic keeps it co-located with the design it describes. The downside: annotations don’t capture system-level decisions that span multiple sheets.

Diagrams-as-code. Tools like Mermaid, PlantUML, or Graphviz generate diagrams from text descriptions. The text source is version-controllable, and the diagram updates automatically when the text changes. Useful for block diagrams that change frequently.

Project notebooks. Physical or digital notebooks (OneNote, Notion, plain lab notebooks) capture informal design thinking, calculations, test results, and decisions. They’re less structured than formal documentation but capture the thought process that formal documents miss.

Wiki or documentation sites. For larger projects or teams, a wiki provides structured, linked documentation. Overkill for personal projects but valuable when multiple people need access.

The Audience for Architecture Docs#

Documentation is communication, and effective communication requires knowing the audience:

Future self. The most common audience. Six months later, the project gets picked up again and needs to be understood — what was done and why. The context, the alternatives considered, and the rationale for decisions will be forgotten. Write for someone with the same skills but none of the current context.

Collaborators. Anyone else working on the project needs to understand the architecture without a verbal walkthrough. The block diagram, interface definitions, and design decisions provide enough context to contribute without breaking things.

Reviewers. Architecture documentation provides the context needed for useful design feedback. A reviewer who only sees the schematic can comment on circuit details but can’t evaluate whether the architecture is sound.

Repair and maintenance. Someone debugging a failed unit needs to understand the system architecture to isolate the fault. Which block does what? Where are the interfaces? What are the expected signal levels? Architecture documentation turns a debugging nightmare into a systematic investigation.

Tips#

• Write a one-paragraph design decision record at the moment a non-obvious choice is made — the five-minute investment prevents hours of re-investigation later
• Start every project with a minimum viable documentation set: block diagram, interface table, and decision log — even if each is just a few lines
• Keep documentation co-located with design files in the same repository or project folder so both evolve together
• Use a living block diagram as the single canonical view of the system architecture, and snapshot it at each board revision

Caveats#

• Documentation written after the fact is worse than documentation written during design. The rationale for decisions fades quickly — write decision records at the time the decision is made, not after the board is fabricated
• Too much documentation is as bad as too little. A 50-page design document that nobody reads provides no value — keep documentation focused on what’s useful: block diagram, interfaces, and decisions
• Diagrams without labels are decoration. A block diagram with boxes and arrows but no signal names, voltage levels, or data rates is a picture, not a design tool — the labels carry the information
• Avoid documenting what the schematic already shows. There’s no need to write “R1 is connected between pin 3 and pin 7” — documentation should capture what the schematic can’t: why, alternatives, and constraints
• Undocumented decisions will be re-litigated. Without a record of why a decision was made, the next person (or a future revisit) will question it, possibly reverse it, and potentially reintroduce the problem the decision was meant to solve
• Version-control documentation alongside design files. Documentation that lives in a different location from the schematic and layout will eventually drift out of sync