Architecture Documentation Revisited

Did you ever read a novel which later has been used as foundation for a movie? I bet, you were rather disappointed how the movie differed from your reading experience and thus from your expectations.

Did you ever read an architecture document – yes, there is vague evidence and hope that something such as architecture documents exists – and then compared the documented design with the implemented system?

In software architecture design, documents are not just by-products created for write-only brain dumps.  Instead, they are supposed to be read by someone – a fact that might be surprising for some engineers.

Architecture documents serve as the basic means for communicating architectural decisions, i.e. they explain the “what” and the “why” – aka design rationale. Target audience of architecture documents are foremost all stakeholders, not just the authors themselves.

In addition, those documents should be up-to-date. Did you ever struggled through 100s of pages of a design document, and right after you finished, someone told you, the document was outdated?

Does this mean, we should adapt the documentation after each change? No, it only implies, architecture documents should be updated regularly. Consider versioning architecture documents in this context!

An architecture specification should also be subject for testing. Don’t take testing too literally! What I suggest is that documents are being reviewed for their usability/readability, internal consistency and completeness, as well as their consistency with the actual implementation. Needless to mention, that the reviewers shouldn’t be the authors but a selection of stakeholders.

Always use the right style of documentation depending on purpose and target audience. A user document that describes a system should contain tutorials as well as a reference manual. If no one understands it, the best design ever won’t help you much.

My strategy for documenting is to walk to the other side of the fence thinking about how a specific stakeholder would like to get the material presented. I am not writing the document for myself but for others, anyway. And I always take care of updating the documentation whenever the system has been updated to a new (minor or major) version. Readers should not be punished by reading my document but consider this as an entertaining and profitable activity. Reading design documents is fun or at least should be! Who claims, IT documents must always be written in a technical and boring style?

Remember: the most important capability of a software architect are communication skills. Documenting is one particular way of communicating.