Software Architecture
 Architecture Trends |
|
Software Architecture |
||||
|
||||
| Architecture Documentation | ||||
It's a stereotype that techies don't much care for producing documentation. Like most generalizations, it has some truth to it, but I, for one, love writing. (Can you tell?) On my current project, I started architecture documentation with the Four Plus One views, but it never felt right. I wanted to slice the layers apart and show them separately, but also wanted to follow certain functional areas from top to bottom, plus fit in developer cookbooks and the rationale for customizations in a vendor package. I wound up with a web site that cuts through the subject in multiple directions with liberal hyperlinking. You can follow the documentation in any dimension, in ways you never could with a paper document.
Code comments are a different story. I've come to believe "if you need documentation to explain code, there's something wrong with the code" and my comments have become more spare as I deliberately write code that explains itself. In my Java work I focus on documenting packages and public methods where the JavaDoc can help somebody use classes without seeing the code.
But systems in the large benefit from good architecture documentation. The following is borrowed from Software Architecture Documentation in Practice at the Carnegie Mellon Software Engineering Institute. There is much more about documentation on the page, and much more about everything at SEI.
This perspective on architecture is forward-looking, involving steps of creation and refinement. Stakeholders include those involved in managing the project, as well as "consumers" of the architecture that must write code to carry it out, or design systems that must be compatible with it. Specific uses in this category include the following:
This perspective on architecture is, in some sense, inward-looking. It involves making prospective architectural decisions and then projecting the effect of those decisions on the system or systems that the architecture is driving. Where the effect is unacceptable, the relevant decisions are re-thought, and the process repeats. This process occurs in tight cycles (most architects project the effect of each of their decisions) and in large cycles (in which large groups of decisions, perhaps even the entire architecture, are subjected to formal validation). In particular, architecture provides the following:
This perspective on architecture is reverse-looking. It refers to cases in which the system has been built and deployed, and now the time has come to make a change to it or to extract resources from it for use elsewhere. Architecture mining and recovery fall into this category, as do routine maintenance activities. In particular, architecture serves the following roles:
It should be clear from this discussion that architecture documentation is both prescriptive and descriptive. That is, it prescribes what should be true, and it describes what is true, about a system's design. In that sense, the same documentation serves both purposes, and rightly so. If the "build-as" documentation differs from the "as-built" documentation, then clearly there was a breakdown in the development process.
However, the best architectural documentation for, say, performance analysis may well be different from the best architectural documentation we would wish to hand to a module implementer. After we introduce architectural views and other architectural documentation, we will return to the roles of architecture and discuss what documentation strategies are well suited to each role.
| Architecture Trends |
