P.7. Summary Checklist

• The goal of documenting an architecture is to write it down so that others can successfully use it, maintain it, and build a system from it.
• Documentation exists to further architecture's uses as a means of education, as a vehicle for communication among stakeholders, and as the basis for analysis.
• Documenting an architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one view.
• The module viewtype helps architects think about their software as a set of implementation units. The component-and-connector viewtype helps architects think about their software as a set of elements that have runtime behavior and interactions. The allocation viewtype helps architects think about how their software relates to the nonsoftware structures in its environment.
• A viewtype constrains the set of elements and relations that exist in its views. An architectural style is a specialization of a viewtype's elements and relationships, together with a set of constraints on how they can be used. A style defines a family of architectures that satisfy the constraints.
• Some styles are applicable in every software system: decomposition, uses, deployment, and work assignment, for example. Other styles occur only in systems in which they were explicitly chosen and designed in by the architect: layered, communicating-processes, and client-server, for example.
• Follow the seven rules for sound documentation. Some styles are applicable to every system; others apply only to those for which they were chosen and architected in. And even styles that apply to every system will not always be documented.

  - Write documentation from the point of view of the reader, not the writer.

  - Avoid unnecessary repetition.

  - Avoid ambiguity. Always explain your notation.

  - Use a standard organization.

  - Record rationale.

  - Keep documentation current but not too current.

  - Review documentation for fitness of purpose.

• There are many views on views. See Chapter 11 for a discussion of how the views described in this book relate to the others.
• Use arrows carefully. Always say what they mean.