Why documentation is always out of date
Architecture documentation usually starts well: somebody spends a week writing it and drawing the diagrams. It dies shortly afterwards, for a simple reason: it lives somewhere other than the system. Every change to the system requires remembering to change the document too, and nobody remembers.
The problem is not one of discipline. It is one of design: if maintaining the documentation is a separate job, it will not get done.
Documentation as code
The alternative is to treat documentation exactly like code:
- It lives in the same repository as the system and is reviewed in the same changes.
- It has a single source: the text in a simple format and the diagrams described as data, not drawn by hand.
- The outputs are generated: document, diagrams, web page and printable version all come out of that source with a common template. They are never edited by hand.
- A shared visual standard: the same colours, icons and structure across every document in the organisation, so they all read the same way.
What to include and what not to
Useful architecture documentation is short and stable:
- Overview and zones.
- Components and what each one is for.
- Main flows, numbered.
- Agreed quality requirements.
- Decision records.
- How it is deployed and how it is recovered.
Whatever changes every week (exact versions, addresses, counts) is not written by hand: it is obtained from the system itself or linked to.
The proof that it works
Architecture documentation is alive if somebody new can understand the system in an afternoon and if an architecture change is not considered finished until the documentation reflects it. The second is only possible if updating it is as easy as changing a line in the same repository.
How we apply it: Cloud Architecture.