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.