Paul’s blog

Markus Völter did a tutorial on Software Architecture Documentation in the Real World at OOPSLA 2007.

The PDF of the slides covers several topics and aspects of architectural documentation. It also shows a few examples of different types of facets and compares the good and bad cases. For many this might be a reasonable first pass at a style guideline for architectural documentation.

It also discusses modeling using UML and Architecture Description Languages (ADLs). On page 87 it has a table that provides some comparison criteria between using UML and ADLs for modeling.

The tutorial even delves into tools, media channels for delivering the documentation, and brushes upon typography.

This is a reasonable introduction for someone working in an organization that doesn’t have any pre-existing practices wrt architectural documentation and for people that have been tasked with creating a company standard for architectural documentation.

Software Architecture Documentation in the Real World – the PDF is 120 pages.