Session:Documentation--Results

From WICSA Conference Wiki

“Documentation in Practice” was a working session to investigate issues involving the creation, evolution, and uses of software architecture documentation. Major topic areas included:

· Enforcement/traceability: How can architecture documentation be structured and/or supported to facilitate consistency between architecture and implementation?

· Tooling: What would a superb architecture documentation tool look like and what services would it provide? Here, a major need emerged: automation to support multi-view consistency checking, as well as “round-trip engineering” to code. A theme throughout this discussion was the strong need (so far, not satisfactorily addressed) to maintain consistency and connections between architectural constructs and downstream artifacts, especially implementation. A useful tool also might help to generate architecture-based test cases.

· Inhibitors: why isn't documentation universally produced? What are the inhibiting factors? Here, participants proposed that we should focus on “just in time” architecture documentation, rather than our traditional model of producing a voluminous, “complete” set of documentation for downstream consumers. The operative question here is, “What do I produce now, and for whom, to deliver best value?” Knowing that answer to this question – or at least asking it consciously – should help an architect deliver documentation that is most useful to its consumers.

· Uses of documentation. Can documentation ever take the place of a person? Does the role of documentation include protecting the project from architects who walk in front of busses? Participants were divided on this; all agreed it would be useful if documentation had the high fidelity to serve this purpose, but it is not at all clear that this goal is achievable. However, the solution to this question is tied up with the solution to the previous question – producing documentation that’s needed at the time should produce documentation that’s of best value.

· UML and architecture: What would it take to make UML a true architecture description language? Here, the answer centered on providing views as first-class concepts. But there is a long list of other things UML is lacking before it can become a first-class ADL as well, including · an extensible meta-model for "real" connectors, security models, etc. · a textual syntax for ease of translation to/from other languages · a variety of representations · making views (as oppposed to diagrams) a first-class concept, as well as operations on views · perhaps an accommodation to ACME · the ability to accommodate domain-specific concerns, views, and notations The question remains: Should we try to use other languages based on their own merits and translate those to UML?