Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Article: Virtual Panel on Software Architecture Documentation

Article: Virtual Panel on Software Architecture Documentation

Software architecture documentation is an important part of the enterprise application development process. InfoQ conducted a virtual panel on this topic to find out, from leading software architecture experts, the significance of software architecture documentation and how to document the architectures in Agile Software Development environments.

The panelists who have answered our questions are:

Len Bass, Senior Member of the Technical Staff at Software Engineering Institute (SEI), co-author of the books Software Architecture in Practice and the upcoming 2nd edition of  Documenting Software Architectures: Views and Beyond.

Grady Booch, IBM Fellow, author of Handbook of Software Architecture web site.

Paulo Merson, Senior Member of the Technical Staff at Software Engineering Institute (SEI) and co-author of  Documenting Software Architectures: Views and Beyond book.

Eoin Woods, Head of the Application Architecture group at Barclays Global Investors, co-author of "Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives" book.

Some of the items included in the panel discussion are:

  • Role of software architecture documentation in Agile software development environments
  • How do UML features like "Profiles" and "Stereotypes" help in documenting software architecture?
  • Best practices that software architects should keep in mind when documenting their software architectures
  • Role of software architecture documentation efforts in the current economic and market conditions
  • Future of software architecture documentation

The key to understanding a project's architectural documentation needs is to understand the role that architectural documentation plays in a project's life cycle. The fundamental reasons why a project produces architectural documentation are communication, analysis and record keeping (e.g. keeping track of decisions over time so they don't get lost). The amount and type of architectural documentation produced by a project should reflect the communication and analysis needs for the product being produced by that project.


Architectural documentation is used to communicate from a project upwards to its management, from an architect or lead designer to the developers, and from a project across time to future maintainers and developers. Just this simple statement leads to three of the questions whose answers help determine the amount and type of documentation. How much oversight is being placed on the project, how many developers and of what skill level are developing the product, and how long lived is the product going to be? The more oversight, the more the need exists for documentation to communicate to management. The more developers and the lower their skill level, the more the need exists for developer guidance. The longer the product is envisioned to live, the more the need for documentation to communicate to future developers on the product.

Communicating to management:
Management may want to know what resources are needed to develop the product and to operate the product. During development, management may want to know what progress is being made on what portion of the system or on what features and what risks have arisen and how they relate to the portions of the system. The module decomposition view and the deployment view (see Documenting Software Architecture: Views and Beyond for a description of views and the different types of views) provide a vehicle for communicating this type of information.

Communicating to developers:
Developers will need to know the portion of the system on which they are working, the constraints on that portion of the system, how their portion interacts with other portions of the system, and what decisions have been already made on the design of their portion. A wide number of views could be used to convey this information but each view comes with a cost so keeping the number of views small is advantageous. Certainly, at a minimum there ought to be a view that shows the static structure (a module view), a view that shows the dynamic nature of the product (a component and connector view), and a view that shows the allocation to hardware (a deployment view). Considerations that affect the type and amount of this use of the documentation are the number of developers - the more developers, the less oversight and personal contact from the lead developer or architect and the greater the need for formal documentation, the skill level of the developers - the more skilled a developer, the less formal documentation is needed, the location of the developers - developers that are collocated with the lead designer or architect have informal methods of finding out information and, consequently, a small need for formal documentation, and the contractual arrangements of the developers - developers that are under a contract to produce a portion of the system will need to have the expectations on them put into contractual terms and this limits flexibility and requires more formal documentation.

Communicating across time:
The more the project is mission critical and the longer it will live, the greater the need exists for formal documentation. The people who will work on the project in the future will likely not be the people who are developing it (how many of us want to work on the same project for multiple years). New people need an introduction to the system and how it works. This requires the same set of views as the current developers. The more mission critical a product is, the more documentation the organization should require.


Analysis needs can come from internal sources to determine the quality of the product with respect to performance, security, reliability, and so forth or from external sources to determine compliance with regulatory or standards based requirements. Early quality tests will require design documentation since the product does not yet exists. Some post production compliance tests can be done through testing the product itself and others will require an analysis of the design of the system. The type of documentation that will need to be produced to satisfy analysis needs depends on the type and timing of the analysis.

Read more about the virtual panel here.

Rate this Article