This chapter is from the book
P.6 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.
- Documentation should pay for itself by making development activities less costly.
- Module styles help architects think about their software as a set of implementation units. C&C views help architects think about their software as a set of elements that have runtime behavior and interactions. Allocation views help architects think about how their software relates to the nonsoftware structures in its environment.
- An architecture style is a specialization of elements and relations, 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. Other styles occur only in systems in which they were explicitly chosen and designed in by the architect.
- Follow the seven rules for sound documentation.
- 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.