Software architecture documentation has one job: let someone who wasn't in the room understand why the system looks the way it does. Most advice on the topic lists the artifacts, a folder of diagrams, a README, a wiki page nobody has opened since the sprint it was written in, without answering the question that actually matters to a CTO staffing a team: which single document, if you only wrote one, would get a new engineer productive fastest? The answer is the architecture decision record. It's the single most useful document a team can keep.
What software architecture documentation actually is
Software architecture documentation covers three things: the structure of the system (what the major pieces are and how they talk to each other), the decisions that produced that structure (why this database, why this service boundary, why not the alternative), and the constraints that shaped both (budget, team size, a client requirement, a deadline). Code comments explain what a function does. API docs explain how to call something. A wiki page explains whatever the last person who touched it remembered to write down. None of those three answers the question a new engineer actually asks first: why does this system look like this, and what would have to change before I could safely touch it.
ISO/IEC/IEEE 42010 is the formal standard for architecture description. C4 and arc42 are where most working teams start instead: both are built for engineers to use day to day.
Why skipping it shows up fastest when an engineer is new
An engineer who's worked on a team for two years can fill documentation gaps with memory: a hallway conversation from eighteen months back, a Slack thread from before the last reorg, a sense of who to ask. An external engineer, a new hire, a contractor, someone brought in nearshore for three months, has none of that. They have whatever's written down. If the answer to "why does this service talk directly to the database instead of going through the gateway" isn't documented anywhere, they either guess or wait on someone else's time.
That gap shows up first in code review. A reviewer without documented context has to reverse-engineer intent from the diff itself instead of checking it against a written decision, and reviewing a pull request without the architectural context behind it turns every review into an investigation, regardless of how senior the reviewer is.
It also shows up in the productivity numbers nobody tracks directly. The data is thin, and how little is actually measured about ramp time for new engineers shows it. The logic holds anyway: what's written down before someone arrives shapes how fast they get productive, whether or not anyone's measuring it. A live technical session focused on architectural reasoning, the kind HighCircl runs as one stage of vetting an external engineer, tells you whether someone can read a decision and reason from it. It doesn't help if there's no decision written down for them to read.
How to document software architecture
1. Write the context first, before any diagram
Before any diagram gets drawn, write two paragraphs: what problem the system solves, for whom, and what's explicitly out of scope. Skip this and every diagram that follows lacks the one piece of information a reader actually needs to interpret it correctly. A box-and-arrow diagram of five services means nothing to someone who doesn't know whether the system serves ten users or ten million, or whether it needs to survive a data center outage. Context doesn't need a template. It needs to exist before the first diagram.
2. Record decisions as you make them, not after
An architecture decision record is what Michael Nygard proposed in a 2011 blog post that's still the reference most teams eventually land on: a short text file in a format similar to an Alexandrian pattern, describing "a set of forces and a single decision in response to those forces." The format has a handful of sections that fit on a page or two: title, status, context, decision, and consequences.
Context describes "the forces at play, including technological, political, social, and project local" factors, whatever pushed the decision one way over another. Decision gets "stated in full sentences, with active voice," the way Nygard's own example reads: "We will …" followed by the actual choice. Consequences is the section teams most often shortchange, and Nygard's guidance on it is direct: "All consequences should be listed here, not just the 'positive' ones."
Write the record when the decision gets made, not months later when someone asks why. Nygard's format runs "one or two pages long," in "a lightweight text formatting language like Markdown or Textile," short enough that lack of time stops being a credible excuse.
3. Pick one diagramming model and stop debating it
Diagramming debates burn hours that documentation itself never gets. Pick one model and move on.
The C4 model is, in its own description, "an easy to learn, developer friendly approach to software architecture diagramming," built around four levels: "software systems, containers, components, and code." Simon Brown created it, and its value is the same as an ADR's: a fixed structure means nobody has to invent a diagramming convention mid-project. The model's own guidance is that the system context and container diagrams are sufficient for most software development teams, answering what a new engineer needs on day one. Component and code-level diagrams earn their keep for the piece of the system someone's about to change.
arc42 takes a different approach. Instead of levels of a diagram, it's a documentation template built to answer, in its own words, "what should you document and communicate about your architecture, and how." It covers "twelve sections, each with a clear purpose, tailorable to your specific needs," created by Peter Hruschka and Gernot Starke, in use since 2005, and free to use, including commercially, under a CC BY-SA license.
The two aren't rivals. C4 gives you the pictures; arc42 gives you the sections to write prose in around them, including one built specifically for architecture decisions. A team that adopts arc42's structure, drops ADRs into its decisions section, and uses C4 for the container and system views has covered what actually gets asked in an onboarding conversation.
4. Put it where the engineer already works
A wiki page survives until the wiki migrates, or until nobody remembers the password, or until it's page eleven of a search result nobody scrolls to. Documentation that survives contact with a deadline lives next to the code: a docs folder in the same repository, rendered from Markdown, reviewed in the same pull request that made the change it describes. If a decision changes the database schema, the ADR for that decision belongs in the same PR. A separate task on a different board gets deprioritized the moment the schema ships.
The reasoning here is about proximity. An engineer already looking at the code is one click from the doc that explains it, instead of needing to remember a separate tool exists, log into it, and search for the right page.
5. Review and update it on a cadence tied to a real event
A calendar reminder to review documentation quarterly gets skipped the first time a deadline is tight, and then every quarter after. Tie the review instead to events that already force someone to look at the architecture: a major decision (write the ADR, update the diagram it affects), a new engineer starting (their onboarding is the test of whether the documentation actually works), or a due-diligence request.
That last trigger matters more than most teams expect. What a due-diligence review actually checks for in your architecture usually surfaces the gap between what the documentation says and what the system actually does, and finding that gap during an acquisition conversation is a worse time than finding it during a routine onboarding.
What to skip
Documenting everything arc42's template allows for, quality requirements, a risk catalog, a glossary, a deployment view, cross-cutting concepts, all twelve sections filled in before anyone ships anything, is overkill for a team under 20 engineers. It produces something nobody reads and nobody updates, which is worse than no documentation at all because it creates false confidence.
Skip the sections that describe things true of every project, like generic quality goals or a glossary of terms your team already knows, and the sections that document intent nobody's tested yet, like a five-year technology roadmap or a risk catalog for risks that haven't materialized. Write the sections that answer a question someone will actually ask: what does this system do, why does it look like this, what breaks if I change it.
The cost of skipping documentation doesn't show up as a missing wiki page. It shows up as debt. Budgeting for the debt that undocumented decisions create works the same way as budgeting for any other kind of debt: it needs its own line and an owner. It also shows up in delivery metrics that look unrelated on the surface. Lead time for changes, which already suffers when reviews wait on another time zone, gets worse still when a reviewer also has to ask around for architectural context instead of reading a doc.
Frequently asked questions
Do I need both an ADR and a C4 diagram?
Yes. A C4 diagram shows what the system looks like right now: the services, how they connect, what's inside a given container. An ADR explains why it looks that way and what alternative got rejected. A diagram without decision records tells a new engineer the shape of the system and nothing about whether that shape is intentional or accidental. Keep both, and keep them separate: diagrams in one place, decisions in another, cross-referenced by date.
How often should architecture documentation be updated?
On the event, not the calendar: whenever a decision gets made (write the ADR the same day, in the same PR if possible), whenever a new engineer starts (use their first week as the test of whether the docs hold up), and before any due-diligence or audit request. A fixed quarterly reminder is better than nothing, but it catches staleness after the fact instead of preventing it.
What's the difference between architecture documentation and technical documentation?
Architecture documentation covers structure and decisions: what the major pieces are, how they connect, and why they're built that way. Technical documentation is broader and covers how-to: API references, setup guides, runbooks, anything that tells someone how to use or operate something that already exists. A new engineer needs both, but architecture documentation is what lets them judge whether a change is safe before they write it; technical documentation just tells them how to run the tests once they have.
Who should own architecture documentation on a team?
The person who made the decision writes the ADR for it, full stop. A tech lead or architect owns the higher-level diagrams and the overall structure, because that's the person with visibility across the whole system rather than one corner of it. Ownership shouldn't default to whoever's willing, because documentation written by someone without the context to explain the reasoning behind a choice ends up being a diagram with nothing behind it, which is close to useless for the exact person who needs it most: the engineer who wasn't there when the decision got made.