How big is your software architecture document?

And who reads this stuff, anyway?

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).

Size of software architecture documents

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?

About the author

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 for information about his speaking schedule, videos from past conferences and software architecture training.

Re: How big is your software architecture document?

In my current project it's very, very small. In fact, it could be described as 'Oral Tradition'.

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.

Re: How big is your software architecture document?

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!

Re: How big is your software architecture document?

The size of documentation depends on the size of the problem of course. As a general measure I create a software architecture package. Executive summary, targeting technical folks, has about 10-20 pages. The logical design document goes between 50 to 150. And the physical design goes between 50 to 150 as well. I keep quality attributes scenarios document separate, and that is usually about 25 pages. So total is between 135 to 350.

Re: How big is your software architecture document?

Just now I am shocked to see the number of pages in a document that has to describe the interface of a general ATA hardisk. Th size is 350+ pages. Now I am searching google for some Ideas to read this much large documents

Add a comment Send a TrackBack