As a technical architect I sometimes find myself thinking about documentation. And what is the purpose of architectural documentation? I see two primary purposes for this documentation;
- For training purposes, so people know what is and what should be, and
- To support sales and marketing when the potential customer asks those sticky questions about scalability and security. I call these 2nd set of documents, “marchitecture”.
In an XP / Agile world we try to reduce the amount of documentation, cause it usually never gets read anyhow. As a solution I now suggest the following;
- We video record a discussion with the architects as they describe the architecture on a white board. Store this video on disk somewhere (or in a wiki) for later sharing.
- Any architectural components which are client focused should be archived into written documents.
The two primary candidates for this “marchitecture” documentation are; scalability architecture and security architecture. These two are the most commonly requested architecture documents to build customer confidence during the sales and marketing efforts.
