The “Software Architecture Document” Size

* This post strengthen my thought on software project document that is write necessary documents only and make sure the documents work.
The "Software Architecture Document" Size

Written by Arnon Rotem-Gal-Oz   


Simon @ CodingTheArchitcture recently asked "How big is your software architecture document? (and who reads this stuff anyway?)"    He notes that in a user’s group meeting most of the attendees had Software Architect Documents (SADs) that were more than 50 pages long.

It would probably not be too surprising if I said that, in my opinion, the answer is " it depends." Reflecting on some of my past projects, I had SADs that varied in length from a 200+ "write-only"  document*  to a less than 10 page lean document. And the sizes matched the intended usage of the documents. For instance, in the two extremes just mentioned, the first case was a huge mission-critical project with a specific requirement from the customer to have an "official" SAD  and  it was written to satisfy some project milestone (PDR) . The second extreme, on the other hand, was an agile project where the architecture document was a working document, written some 10 iterations into the development to highlight some of the emergent guidelines.

What is common to all the SADs I’ve written (or have been responsible for) is that they all tried to grasp the essence of the design, all used multiple viewpoints to describe the solution, all were focused on quality attributes,  and all explained the rationale behind the decisions.

  • If you drone endlessly with details, you don’t see the forest from the trees.
  • If you don’t use multiple views, you are likely to miss important aspects of the solution
  • If you aren’t focused on quality attributes, then you are most likely documenting design and not architecture
  • And if you don’t explain the rationale,  then the document doesn’t have a lot of added value beyond the code itself

In any event, the important thing here is that when it comes to Software Architecture Documents  "size doesn’t matter" :). What matters is that the SAD satisfies  the reason it was written for.

*While this particular SAD was rather long,  it also had a section that helped potential readers find relevant chapters so that it can actually be usable, and not just for "door stopping".

The “Software Architecture Document” Size

One thought on “The “Software Architecture Document” Size

  1. Unknown says:

    Welcome to cheap wow gold our wow Gold and wow power leveling store. We wow gold are specilized, wow power leveling professional and reliable wow power leveling website for wow power leveling selling and wow gold service. By the World of Warcraft gold same token,we offer buy wow power leveling the best WoW service wow power leveling for our long-term and wow powerleveling loyal customers. wow powerleveling You will find wow powerleveling the benefits and value powerleveling we created powerleveling different from other sites. As to most people, power leveling they are unwilling to power leveling spend most of wow power leveling the time buy wow gold grinding money Rolex for mounts or rolex replica repair when replica rolex they can purchase Watches Rolex what they Rolex Watches are badly need. The Watch Rolex only way is to look Rolex Watch for the best place rs gold to buy cheap WOW gold. Yes! You find it here! Our WoW Gold supplying service has already accumulated a high reputation and credibility. We have plenty of Gold suppliers, which will guarantee our delivery instant. Actually, we have been getting Runescape Gold tons of postive feedbacks from our loyal RuneScape Money customers who really appreciate our service. -120221821380921

Leave a Reply