A minimal approach to software architecture documentation

The question of "how much documentation should we write?" is popping up a lot recently, probably driven by teams looking at their business continuity plans, and the increase in remote working. Many software developers will be quick to tell you that:

• "we're agile"
• "we value working software over comprehensive documentation"
• "the value is in the conversation"
• "the code is the documentation"
• "the tests are the documentation"

The code is the truth, but not the whole truth

As Grady Booch will tell you though, "the code is the truth, but not the whole truth". Although we should definitely strive for highly modular code, and naming that expresses intent rather than relying on comments, the code doesn't tell you things like:

• What is the context of the thing we're building?
• Who are the people using the project/product?
• What interfaces does it have with other software systems, inside and outside of the organisation we work for?
• Where is the software system deployed?
• How do we support it?
• What were the drivers that led the team to building the software system in the way they did?
• What led to the early decisions being changed?
• etc

Describe what you can't get from the code

With this in mind, and remembering that time is precious, here's my suggestion for a minimal set of software architecture documentation.

• A System Context diagram
• A Container diagram
• One or more Deployment diagrams
• Some lightweight Markdown/AsciiDoc documentation (e.g. software guidebook, or arc42)
• Architecture decision records (ADRs)

Consider this a starting point, and it should ideally be stored alongside the source code. If you need a few code level diagrams to document parts of your codebase, feel free to add some UML Class or Sequence diagrams. If you need to document business processes, then add some UML Activity diagrams, or perhaps take a look at ArchiMate. Ditto wireframes, entity relationship models, domain models, state charts, API definitions, etc.

Summary

Although statements such as "the code and tests are the documentation" is not necessarily incorrect, we should still strive to add something a little higher level, describing what we can't easily get from the code.