I'm going to write-up my notes from the last London user group (Sharing Architectures) later in the week, but I wanted to pose a question to you that I asked at the user group. How big is your software architecture document for your current project/system and what sort of information does it contain? Here's a graph summarising the size responses from the user group (small turnout this month).
As you can see, most people's software architecture documents are ~50 pages and above, which my experience suggests isn't uncommon. How does this compare to yours and does anybody read these documents?
Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.
You can find Simon on Twitter at @simonbrown ... see simonbrown.je for information about his speaking schedule, videos from past conferences and software architecture training.
In my previous project we had hundreds and hundreds of pages. Which was just as much of an issue. It was impossible to keep up to date and no one ever read it. Ah for the happy medium.
On a recent rash of waterfall projects the SADs were in the 80-150 page range. However, I suspect that each contained only 10-20 pages of insight.
These documents were read fairly thoroughly by the offshore team, though! Perhaps in the absence of someone to talk to about the architecture or requirements the documentation acts as a surrogate (albeit a substandard one IMHO).
Very few people onshore bothered to read the SAD - they relied on the information being presented to them instead. In terms of reviewing the architecture, the latter seemed to work best!