Rob Reed

Wednesday April 16, 2008

"Mine is an architecture documentation project"

• That's still true, but the emphasis and scope of what I'm doing is significantly different.

I started with the goal of completing what I called a 'case study'.

• Writing the architecture documentation for another project of mine (Ode).

Something was missing

• I didn't know how to apply the theory to my existing project.
• More generally, I was missing an approach to applying what I believe is a strong theoretical framework to the job of putting together the architecture documentation for any one specific project.

What I came up with is a general model for writing architecture documentation.

Early in the semester we were asked to read the prologue to the book "Documenting Software Architectures: Views and Beyond", which presented this list of 'Rules for sound documentation':

Documentation should:

• Be written from the reader's point of view
• Avoid unnecessary repetition
• Avoid ambiguity
• Use a standard organization
• Record rationale
• Be kept current but not too current
• Be reviewed for fitness of purpose

Are these rules enough?

From the same reading assignment we have this definition

Architecture is what makes the sets of parts [of a system] work together as a successful whole. Architecture documentation is what tells the developers how to make it so.

We are told that architecture documentation should be:

• Abstract -- to be quickly understood
• Detailed -- to serve as a blue-print for construction
• Informative enough -- to serve as a basis for analysis
• Prescriptive -- prescribing what should be true
• Descriptive -- describing what is true

And that it should serve as:

• A means of education
• A primary vehicle for communication among stakeholders
• The basis for system analysis

The "IEEE Recommended Practice for Architecture Description and Software-Intensive Systems" (IEEE Std 1471-2000)

presents four scenarios "intended to suggest the range of uses of the recommended practice"

1. Architecture of single systems which deals with new system construction
2. Iterative Architecture where the architecture, delivered systems, and stakeholders co-evolve
3. Architecture of existing systems which is relevant when there has been development without a corresponding architectural description
4. Evaluation, the purpose of which is to include the quality of architectural description and predict the quality of systems based on that description.

These scenarios...

• speak to the importance of architecture documentation as a persistent influence.

• suggest that architecture documentation can be introduced at any point in the life cycle of an architecture.

This is my list of critically important concepts:

• The concept of the view;
• The role of architecture in suppressing information not relevant to the task at hand;
• A commitment to representing the interests of stakeholders;
• The idea that the architecture documentation and the architecture itself exist and are maintained together throughout the entire life cycle of the architecture;
• The importance of considering elements which are included as part of the architecture and its environment, at any point in the life-cycle. And to do so in such a way that these elements are fixed (i.e. dependable or unchanging) with respect to the architecture.

All of these figure prominently into my approach and the resulting model.

If one thing is clear from what we've discussed in this class it's that the work we set out to do is difficult and it isn't getting any easier.

For all of the problems we had with the autonomous computing paper, here is a quote from the article that no one was bothered by enough to refute:

Computing systems' complexity appears to be approaching the limits of human capability, yet the march toward increased interconnectivity and integration rushes ahead unabated.

Though not the answer to all of our software complexity woes, we can

• better manage the problem today
• and lay the groundwork for future innovation

by improving the tools and techniques we use to document software systems.

Easier doesn't necessarily mean easy.

We have few well established patterns for dealing with documentation.

There are many questions that must be answered before we can hope to do an adequate job with architecture documentation.

• Where to begin?
• How do we manage this wealth of documentation that is being, or has already been generated by others involved in the system?
• How do we describe the documentation itself (i.e. how do we document the documentation)?

These are not the only challenging questions.

The existence of multiple documents

• Risks fracturing the attention of people involved in the system;
• Allows for the possibility of parts of the documentation disappearing;
• Can lead to disagreement or confusion about what has been done and what still needs to be accomplished.

It is not uncommon to find ourselves in a situation where we have multiple and competing documents, or multiple versions of the same document.

• Leads to misunderstanding, misrepresentation, and ultimately architectural confusion (i.e. confusion about what the architecture is).

A one document approach may be interpreted as a single task.

• The work may be assigned to one person or group.
  • May require an unreasonable amount of time and effort to put together
  • Documentation is often either neglected or passed along to a separate group, who are not necessarily the best people for the job.

Writers of technical documentation are often detached or isolated from the development groups.

• Often leads to misunderstanding and inconsistencies between the documentation and the implementation itself.

Although the architecture documentation is intended to prescribe how a system should work, if it does not adequately describe the current behavior, it may be regarded as irrelevant

• This may instead describe a functional but broken implementation which doesn't agree with the intended architecture.

We are often unrealistic about the investment required and as a result do not set aside adequate resources for documentation.

The ability to write documentation well is a skill that not everyone involved in the development of software possesses, or practices.

• The emphasis of documentation in education, or lack thereof, may be an important factor.

We said early in the semester that software development is essentially linear, and that this may contribute to our inability to properly specify complex architectures.

• Documentation has remained stubbornly linear (whether or not this is true of software development)
• Even with architecture description languages, (a la UML), our diagrams are typically one of a linear set of ideas bound together that must be considered from beginning to end to be understood.

Lastly, we may want to question some of the the assumptions that underlie the stated goals of architecture documentation.

• Is it appropriate to expect any one person, or small group, to anticipate or be capable of adequately representing the unique and often divergent concerns of all stakeholders?
• Do we expect the architect to write the architecture documentation?
  • Is this reasonable given the unsettled role of the architect?

How might we address some of these problems?

In my estimation must be able to:

• Compose documentation (i.e. produce many views of a single document);
• Bridge architecture and implementation level documentation;
• Minimize the effort required to produce the architecture documentation by incorporating work which has already been done;
• Establish a connection between the the architecture and the architecture documentation;
• Involve everyone in the documentation effort, such that the collected knowledge about the architecture is reflected in the documentation;
• Explore nonlinear approaches to documentation, so that we can preserve detailed knowledge about the architecture without exposing an overwhelming amount of information;
• Pursue an approach that is flexible and adaptable enough to accommodate the potentially unique and varied concerns of existing stakeholders as well as meet the needs of new stakeholders.

Each documentation component is essentially a package of progressively more detailed versions of the documentation for one element of the architecture.

These include a wide variety of architectural elements related to the architecture

Anything we want to

• represent in one or more views of the architecture documentation.
• describe in greater detail

Imagine that all of these documentation components arranged in a grid

• That grid, which I'm calling a documentation component browser, defines the scope of the architecture.

The browser allows us to:

• Navigate any of the individual documentation components
• Define, edit or delete components
• Filter the collection of documentation components based on associated attributes or metadata
• Search over the entirety of the architecture documentation
• Select from a list of views to highlight only those components that are included in the view
• Create new views and assign documentation components to views

The browser does not show connections between documentation components.

• Doing so would violate the key concept that views hide documentation that is not relevant to the task at hand (and lead to confusion).

We need another interface for composing views.

When we select any view (from an collection of views available in the browser), The documentation components of that view are highlighted.

If we choose to compose the view the browser's grid drops away.

• Leaving only the components associated with the view
  • which we can then manipulate by connecting and rearranging them for example.

By connecting the documentation components, we specify relationships among the documentation, in a way that is similar to what you might think of doing with an abstract ADL.

• The purpose is to allow us to reason about a system that either we intend to build, or one which already exists.

A view is a physical document in the sense that it can be printed, copied and shared.

• We define a single architecture document and use it to hide, selectively expose, and manipulate what may be hundreds, or thousands member documents.

• From this one document we can produce many more, each with a narrower focus, and each potentially tailored to the needs of a particular stakeholder.

The model supports two approaches to documenting relationships in the architecture.

1. We can include relationships among the documentation components, and then compose them using only 'dumb' connections (which indicate nothing more an ordering over the documentation).
   • With this approach, we can take advantage of the expressive power of our components as packaged abstractions.
2. We can also choose not include relationships among the documentation components and instead deal with them as part of composition...
   • in which case we need a more robust collection of graphical objects and tools for connecting documentation components.

This is a decision for the architect

• If connections are very complex then we may choose the former approach.
• In an environment where a description language like UML is already commonly used, then it may be more appealing to deal with connections as part of the composition

Who are these stakeholders?

They may be roles, or individuals (i.e. specific people) involved with the architecture.

• There may be many such stakeholders, with narrowly defined concerns.

Is it possible to anticipate the needs of all of these stakeholders?

• No, I would argue that it's not.
• A better approach is to allow stakeholders to generate their own views that meet their unique needs.
  • in addition to a set of stock views which are composed by the architect herself.

They are reusable.

• Each is one of a library of components.
• Documentation components can appear in the browser, in one or more views, or part of another component's abstraction hierarchy.

Is everything a documentation component?

No. Consistent with other ideas about architecture documentation, there are both architecture and implementation level details.
• Architectural level details are represented as documentation components.
• Implementation level details are simply graphical, or textual descriptions of some part of a system.
  • These appear (only) as part of the abstraction hierarchy for some architectural element and lack details of their own.

The approach is intended to be nonlinear, flexible, and adaptive.

To this end it:

• Defines the scope of an architecture including the environment (as described by the IEEE recommended practice)
• Allows for composing documentation in response to the needs of the stakeholders
• Bridges between what is typically considered architecture and implementation level documentation.
• Is general purpose enough to work with many different styles of architecture.
• Emphasizes the key concepts of architecture documentation (already discussed).
• Is implementable and adoptable now.
• Does not introduce a lot of overhead beyond what is necessary to realize an architectural vision of the system.
• Is easy to understand.

The model is adoptable now

After reading the Rapide paper, the class talked about whether the strategy epitomized by that language is adoptable

• given the current culture and prevailing approaches to the job of software engineering.

Can we pursue architecture-based approaches without architects?

• I would suggest that the answer is no, and that this is a fundamental disconnect between what we suppose we must do to be successful, and what we are capable of achieving based solely on theoretical or technical progress.

In comparison, I believe that the modest idea I'm proposing is adoptable now because it reflects the developer-driven organizational style that currently dominates software projects.

• What's more, this model can serve as a bridge to a potential future when the field may be more architecturally driven.

Because it is a documentation model it does not place any restrictions on or make any assumptions about the system itself.

• A potentially promising solution may not be worth considering if it reduces an experienced development team to a group of novices.

Documentation can serve as a path toward architectural change.

• It's reasonable to think that an architectural approach to documentation may lead to interest in architectural approaches to building systems.

Documentation bridges architecture and implementation level details, serving as a medium for communication between stakeholders.

The model addresses common logistical issues related to maintenance of documentation.

• We are asking everyone involved in maintaining the documentation to do a reasonable amount of work, and to be responsible for parts of the system they are familiar with.

The model introduces only a minimal amount of overhead.

• The model takes advantage of implementation level documentation but does not burden the architect with implementation level details.

Information that is not included in the documentation takes on an active meaning.

Current work

I'm continuing to refine the model by building a 'prototype' that works roughly as described.

• This means that I'm cobbling something together to play with these ideas more.
• I expect that this prototype will be fairly limited in its usefulness, except that hopefully it will help me work out some of the details.

Future work

Ultimately the end result of this may be the development of a set of tools for creating, manipulating and presenting architecture documentation in a way that is consistent with the model as described.

Thank you