{"title":"Platform Toolsmith","subtitle":"Build logs, patterns, and opinions about platform engineering and internal developer tools.","link":[{"@attributes":{"href":"https:\/\/platformtoolsmith.com\/feed.xml","rel":"self"}},{"@attributes":{"href":"https:\/\/platformtoolsmith.com\/"}}],"updated":"2026-11-02T00:00:00Z","id":"https:\/\/platformtoolsmith.com\/","author":{"name":"Alexandre Castro","email":"alex@platformtoolsmith.com"},"entry":[{"title":"Architecture Starts With a Conversation, Not a Document","link":{"@attributes":{"href":"https:\/\/platformtoolsmith.com\/blog\/architecture-document-types\/"}},"updated":"2026-11-02T00:00:00Z","id":"https:\/\/platformtoolsmith.com\/blog\/architecture-document-types\/","content":"

On our project tracker, a team couldn't move work into Active without filling in two required fields: who approved the architecture, and the date they approved it. On paper, nothing started without an architecture review. In practice, the tracker only checked that those two boxes weren't blank.<\/p>\n

\"A<\/p>\n

Eighty-three items carry that date. Twenty of them share one date. Some of those are mine: the migration that moved the items onto architecture's board wrote my name and its own date. Delivery teams filled in the rest. I can't tell you whether a real decision sits behind any of them, and neither can the field. That's the problem.<\/p>\n

If those were backfilled, it's a team being rational about a gate. Put a field in the way of progress and the field gets filled in. So what's the cheapest way to fill it? A plausible value nobody has to defend.<\/p>\n

\n
\n [ <\/i> WARNING<\/span> ]\n <\/div>

The gate checks that the field is filled in, not that a decision exists behind it.<\/p>\n<\/blockquote>\n

So don't build a gate. Build a language. An architecture function earns its authority by unblocking, and everything in this series comes back to that sentence. None of it works until the teams you're trying to help can understand you, and that shared understanding is a language. In this job, the language is documents.<\/p>\n

Enterprise Architecture By Hand<\/strong> is a five-part guide to running an architecture function with no mandate, no budget and no title. It's for the staff engineer, principal or tech lead who will do it anyway. Each part ends with something you can do the same week; this one ends with seven document types and the full template for each.<\/p>\n

The seven document types<\/h2>\n

Seven document types carry our framework, one question each. Keep the split clean and the rest follows.<\/p>\n

Request for comments (RFC): should we do this?<\/strong> Short, ephemeral, and collaborative: it gathers advice on a significant change before a decision is made, then resolves into an ADR or closes.<\/p>\n

Architecture decision record (ADR): what did we choose, and why?<\/strong> Write the decision once, when it lands, then never edit the decision. The one edit a record allows is the Superseded by line, naming the later record that replaced it. Change your mind and you write a new record.<\/p>\n

Solution architecture document (SAD), the design doc: what is the target state?<\/strong> This one stays alive as the umbrella for a program spanning multiple statements of work, beside the code it describes, because the code is what makes it wrong first.<\/p>\n

Standard (STD): what are the rules today?<\/strong> The living rulebook that codifies durable rules produced by accepted ADRs: the ADRs hold the why, and this document holds the what.<\/p>\n

Runbook (RUN): how do I do it?<\/strong> A procedural, step-by-step operational guide with verification and rollback, implementing the rules that live in standards.<\/p>\n

Statement of work (SOW): what are we delivering?<\/strong> A bounded delivery document that pairs deliverables with acceptance criteria and a minimum viable solution floor, from start to done.<\/p>\n

Opportunity brief (BRIEF): why fund this?<\/strong> A one-page executive pitch in business terms (the problem, the cost of doing nothing, the options, the ask, and the success measures) whose only job is to win sponsorship and spawn a SAD.<\/p>\n

Each of the seven questions has its own lifecycle: ephemeral, frozen, or living.<\/p>\n

    \n
  • Ephemeral:<\/strong> two proposals that do their job and stop. The RFC ("should we do this?") gathers advice until it resolves into an ADR or closes and freezes, and the BRIEF ("why fund this?") pitches the business case in one page until it is funded or parked and spawns a SAD or SOW.<\/li>\n
  • Frozen:<\/strong> two records that do not get rewritten. The ADR ("what did we choose, and why?") is immutable once accepted, never edited except to name the record that superseded it, and the SOW ("what are we delivering?") bounds a delivery and is frozen at done.<\/li>\n
  • Living:<\/strong> three documents that evolve with the system. The SAD ("what is the target state?") updates as decisions land, the STD ("what are the rules today?") is versioned and reviewed on cadence, and the RUN ("how do I do it?") is tested in exercises or incidents and archived when it goes stale.<\/li>\n<\/ul>\n

    If your company has better names for the seven, use those instead, because the words matter less than the questions.<\/p>\n

    How the seven fit together<\/h2>\n
    \n
    \n\nHow the seven architecture document types connect<\/title>\nA funded BRIEF becomes a SAD, which decomposes into SOWs. A big decision during a SOW raises an RFC. A decided RFC becomes an ADR, which rolls up to the SAD and is codified into a Standard, which is applied through a Runbook.<\/desc>\n