How I did not (yet) learn how to write architectural documentation

As I promised in the last posting, here are some thoughts on architectural documentation. They crept out of my mind while I read chapters 6 and 7 of Ian Gorton's "Essential Software Architecture". For such a central topic as the documentation of an architecture, the chapters are astonishingly short. To be fair, the book is not only about the documentation of software architecture, but about all of architecture. Yet, we would expect a solid foundation of how to arrive at a good documentation. Do we get this?

Essentially, chapter 6 of the book is structured like this:

• One and a half pages of introduction
• One page about what to document
• Eight pages of introduction to UML 2.0
• Half a page on having an "Architecture Documentation Template", and a extremely high-level example of one
• Finally, a one-page summary

As I and all my architects and all our analysts know UML 2.0, what remains are four pages of information.

Let's try to dissect the information in them:

1. The first two paragraphs tell the true story that both feeble and massive documentation can be, and "sometimes"(?) is, "out-of-date, inappropriate and not very useful."
2. "But there are many good reasons why we want to document our architectures, for example" so that others, "most commonly members of the design and development team" "can understand and evaluate the design"; "we [whoever we are, in contrast to the development team] can understand the design" later; others can "learn from the architecture by digesting the thinking behind the design" [I do not understand this; isn't that "evaluating the design"?]; "we can do analysis on the design, perhaps to assess its likely performance, or to generate standard metrics like coupling and cohesion."
3. But it's hard to document, and the predominant tools are Word, and Visio and PowerPoint ("along with their non-Microsoft equivalents"), and the notation is "informal 'block and arrow' diagrams". "We should be able to do better."
4. The second section, "What to Document", starts with an example that shows, in my opinion, a huge misunderstanding of what software architecture is:

   A two-tier client server application with complex business logic may actually be quite simple architecturally. It might require no more than an overall “marketeture” diagram describing the main components, and a perhaps a structural view of the major components (maybe it uses a model-view-controller architecture) and a description of the database schema, no doubt generated automatically by database tools. This level of documentation is quick to produce and routine to describe.

I'll show, a few postings down my ramblings, that all the standard books and texts on software architecture notation were, up to now, not able to provide and explain a notation that can even capture this "simple architecture". At the moment, let's just take it that some high-level diagrams seem to be the goal of an archtectural documentation. Why? Because we are told so?
5. However, the section tries to sum up the reasons for more extensive documentation: Complexity ["in the eye of the beholder"? measured somehow? agreed by a team based on gut feeling?]; longevity [again: how evaluated?]; needs of stakeholders. However, this still does not tell us "what" to document; only that it must be "more".
6. Final sentence: "It’s therefore important to think carefully about what documentation is going to be most useful within the project context". I thought and think carefully, and three of us discuss—sometimes more heated than carefully—what documentation is going to be the most useful. We are not very successful at this, I have to admit.
7. The short template, after the UML 2.0 section gets its meat from the case study in chapter 7—an interesting approach dating back to the Babylonians (teach by example, not by abstraction) which, for me, does not really work, because the key point of learning, namely how to apply it in one's own environment, is lacking.
8. The summary again tries to morally uplift us:

   Generating architecture documentation is nearly always a good idea. The trick is to spend just enough effort to produce only documentation that will be useful for the project’s various stakeholders. This takes some upfront planning and thinking. Once a documentation plan is established, team members should commit to keeping the documentation reasonably current, accurate and accessible.

   I remain sceptical and am unable to heed this advice in our team, I have to admit.
   
9. Finally, there is a summary with two main ideas: First, and I agree wholeheartedly for—right now—lack of something better, it favors UML 2.0 as the notation to use, for sketches, for "closely" modelling components and objects, and for "exact" modelling for model-driven development.
10. The other idea in the summary is to have a repository for documentation, with some sort of "automatic documentation production", for whatever purpose and with an unknown functionality.

10 items of information about how to document a software architecture. I do not want to dispute most of them. I have indicated above where I think the text is wrong (and I hope to explain this in more detailed later postings). But here, I want to find out how to proceed with our documentation: And for this, I have not gotten many clues. Why? See my next posting.