rel:: [[Software Engineering]] [[software architecture]] [[process]] - Author:: [[Michael Nygard]] - Source:: <https://blog.cognitect.com/2011/11/15/documenting-architecture-decisions.html> - Source:: <https://www.instapaper.com/read/1305262961> - Recommended By:: # Documenting Architecture Decisions ## Ideas ### Problem > One of the hardest things to track during the life of a project is the motivation behind certain decisions. ### Solution > We will keep a collection of records for "architecturally significant" decisions: those that affect the > - structure > - non-functional characteristics > - dependencies > - interfaces > - construction techniques. See [[Architecture Decision Record]] # Highlights - Agile methods are not opposed to documentation, only to valueless documentation. - ==One of the hardest things to track during the life of a project is the motivation behind certain decisions.== - We will keep a collection of records for "architecturally significant" decisions: those that affect the - structure - non-functional characteristics - dependencies - interfaces - construction techniques. - ==Each record describes a set of forces and a single decision in response to those forces.== Note that the decision is the central piece here, so specific forces may appear in multiple ADRs. - An architecture decision record is a short text file in a format similar to an [Alexandrian pattern]([[A Pattern Language]]). - We will keep ADRs in the project repository under `doc/arch/adr-NNN.md` - We should use a lightweight text formatting language like Markdown or Textile. - ADRs will be numbered sequentially and monotonically. Numbers will not be reused. - ==If a decision is reversed, we will keep the old one around, but mark it as superseded==. (It's still relevant to know that it was the decision, but is no longer the decision.) - We will use a format with just a few parts, so each document is easy to digest. - The whole document should be one or two pages long. - ==We will write each ADR as if it is a conversation with a future developer.== - ==This requires good writing style, with full sentences== organized into paragraphs. - One potential objection is that keeping these in version control with the code makes them less accessible for project managers, client stakeholders, and others who don't live in version control like the development team does. In practice, our projects almost all live in GitHub private repositories, so we can exchange links to the latest version in master. Since GitHub does markdown processing automatically, it looks just as friendly as any wiki page would.