Thursday, November 03, 2005

XP Architecture Documentation

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;
  1. For training purposes, so people know what is and what should be, and 
  2. 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.