Software Engineering
Documentation and ADR
A new engineer on the team. A strange architectural decision. Why MongoDB for financial data? Who made this decision? Without ADR - ask around, read Slack history from 2022, try to reconstruct the context. With ADR - 30 seconds to find the document, full context, alternatives rejected, and the consequences known at decision time.
- **Rust RFC process**: every language change goes through a public RFC. Thousands of comments, months of discussion, documented final decision. The language evolves through structured community input rather than individual decisions.
- **Google Design Docs**: before a major engineering project, a design doc is written. Discussed asynchronously, decisions captured. Engineers can onboard to a new system by reading the design doc history.
- **Stripe API Reference**: fully generated from an OpenAPI spec. Always current, always matching the actual API behavior. No manual documentation updates, no documentation drift.
Architecture Decision Records
An Architecture Decision Record (ADR) is a short text document capturing an important architectural decision with its context, considered alternatives, and consequences. Format: Status (Proposed / Accepted / Deprecated / Superseded), Context, Decision, Alternatives Considered, Consequences.
ADR solves the institutional memory problem: a developer joins the project a year later and sees a strange decision - why MongoDB for financial data? Without ADR - ask the original author (if still on the team). With ADR - read the document that was written when the decision was made, with full context and alternatives rejected at the time.
An ADR accepted a year ago became outdated: the team decided to switch from REST to gRPC. What should be done with the old ADR?
RFC Process
RFC (Request for Comments) is a process for asynchronous discussion and adoption of major technical changes. Rust language uses RFC for every language change. IETF (HTTP, TCP standards) uses RFC for internet standards. The process: author writes a proposal, community discusses, RFC is accepted or rejected with documented reasoning.
RFC format: Problem Statement (what exactly is not working or what needs improvement), Proposed Solution (concrete proposal with examples), Alternatives Considered (why other approaches were rejected), Migration Plan (how to transition without breaking existing systems), Open Questions (unresolved points for discussion).
An RFC proposes switching to a new framework. The 'Alternatives Considered' section is empty - the author is convinced their solution is the best. What does the review team do?
Wiki and Team Knowledge
Team knowledge is stored in several places with different lifetimes: Slack (ephemeral - disappears within months), Email (searchable but not discoverable), Wiki (persistent, searchable, shared), Code (authoritative for implementation), ADR (authoritative for decisions). Each has its appropriate use case.
The 'expensive wiki' principle: document only what has a long lifetime and high value for the team. Signs of a healthy wiki: each page has an owner who keeps it current, pages have 'last reviewed' dates, outdated pages are deleted rather than accumulated. Signs of an unhealthy wiki: pages contradict each other, no one knows which is authoritative.
The onboarding wiki was written a year ago. A new engineer complains that half the instructions do not work anymore. What is the best approach?
Documentation as Code
Documentation as Code (DoC) - storing documentation alongside code in the same repository, in git. Advantages: documentation changes are code-reviewed in the same PR as the code change, documentation versions match code versions, documentation is not forgotten because it is part of the development workflow.
OpenAPI (Swagger) - specification-first API documentation. The YAML/JSON schema describes the API; client SDKs, server stubs, and interactive documentation are automatically generated from it. Stripe's public API reference is fully generated from an OpenAPI spec - always current.
Contract testing (Pact, Spring Cloud Contract): consumer and provider share a contract file. Provider changes are validated against the consumer's contract before deployment. If the provider breaks the contract, CI fails - caught before it reaches production and breaks the consumer.
Good documentation is voluminous documentation - the more is written, the better
Good documentation is accurate, current, and actionable. Voluminous documentation that is not maintained becomes a liability: contradictory information, outdated instructions, pages no one reads. The 'expensive wiki' principle: document only what has long lifetime and high value.
The best documentation is code that is self-explanatory, tests that describe behavior, and ADRs for architectural decisions. Written documentation should supplement these, not replace them.
A developer changed an API endpoint (added a required field to the request). Documentation is in Confluence. What problem does Documentation as Code solve?
Summary
- **ADR**: immutable records of architectural decisions - context, alternatives considered, consequences. Stored in the repository, updated via new ADRs not edits. Institutional memory.
- **RFC**: asynchronous structured process for major changes - problem, proposal, alternatives, migration plan. Used when multiple teams are affected or the decision is hard to reverse.
- **Documentation as Code**: docs in the same repository as code, reviewed in the same PR. OpenAPI spec as the source of truth for API documentation - always current.
Related Topics
Documentation is connected to decision-making processes and leadership:
- Technical Leadership — ADR and RFC are the TL's primary tools for documenting decisions and building institutional memory that survives team changes
- API Design: REST, GraphQL, gRPC — OpenAPI spec is Documentation as Code for APIs: the spec is the contract, documentation is generated from it automatically
Вопросы для размышления
- How to create a culture of documentation maintenance in a team where everyone is busy and documentation is always outdated?
- ADR and RFC - what is the difference and when to use each one?
- How to measure documentation quality for a team - which metrics show that documentation is actually working?