Channels ▼

Arnon Rotem-Gal-Oz

Dr. Dobb's Bloggers

The "Software Architecture Document" Size

April 21, 2008

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

Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 


Video