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.
Communication:
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:
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.
Community comments
broken link
by Fábio Uechi,
Re: broken link
by Srini Penchikala,
A more dynamic documentation
by William Martinez,
Re: A more dynamic documentation
by Paulo Merson,
Re: A more dynamic documentation
by William Martinez,
Architecture Vs Design
by Traxx WiF,
Re: Architecture Vs Design
by Gary Duzan,
Re: Architecture Vs Design
by Wanderson Santos,
Re: Architecture Vs Design
by Traxx WiF,
Re: Architecture Vs Design
by Paulo Merson,
Re: Architecture Vs Design
by William Martinez,
Re: Architecture Vs Design
by Dan Hestand,
Re: Architecture Vs Design
by William Martinez,
Software Architecture Documentation template
by Srini Penchikala,
broken link
by Fábio Uechi,
Your message is awaiting moderation. Thank you for participating in the discussion.
The link to the virtual pannel leads to an error page.
Re: broken link
by Srini Penchikala,
Your message is awaiting moderation. Thank you for participating in the discussion.
Hi Fabio, the broken link is fixed now. Thanks.
A more dynamic documentation
by William Martinez,
Your message is awaiting moderation. Thank you for participating in the discussion.
Interesting.
A document is to read it and use it. It has a cost of updating it. We need to leverage the use benefits and the costs and see if it makes sense.
Uses? Well, a document from code that appears after the press of a button is not so far away with the new tools, but is it useful? Documents extracted from code may contain an abstraction of it, and may help us understand what the code does. But an architectural description should be far more that just a visualization of the code's organization and actions. It should contain rationale, history, decisions, a way to tell how are we doing in accomplishing the business goals.
Documents should be used to lay down an initial path developers should follow, then it should be updated with the changes and decisions made due feedback from development, used to audit if the generated code complies with what it is expected or defined, then used for decision making at high level, used to define a test strategy, and when solution is done, used to fix or enhance in a future the solution.
The moment a document gets out of synch or full of un-useful data, it becomes waste. So, documentation should part of the day-to-day work, not something generated at some point in time and used now and then. If you don't use your docs, then don't generate them. Learn to use docs first, and then be happier.
William Martinez Pomares.
Architect's Thoughts
Re: A more dynamic documentation
by Paulo Merson,
Your message is awaiting moderation. Thank you for participating in the discussion.
I agree, although estimating the costs is hard.
Indeed, the models you obtain from traditional reverse engineering tools don't provide the rationale for the design decisions and usually contain abstractions that are too close to implementation. Architecture reconstruction techniques can recover the architectural design from existing implementation artifacts, but it takes more than the push of a button.
Agreed. Readers don't trust documentation once they find out it's out of date. Some suggestions:
Re: A more dynamic documentation
by William Martinez,
Your message is awaiting moderation. Thank you for participating in the discussion.
Totally agree.
One point I would like to highlight is the actual documentation use. That is, we can have a very good reason to document something, as part of a development strategy, but if the generated doc is not used, or at least no used as it should, then we may have waste. Actually, we may have a warning light of something not quite correct in the strategy!.
That is, we can actually take our time to discuss the document creation, but it is its used what, at the end of the day, counts. We can go a step further: If the use of the docs becomes important in the development, updating and generating becomes essential, and part of the development it self, as much as coding.
William Martinez Pomares.
Architect's Thoughts
Architecture Vs Design
by Traxx WiF,
Your message is awaiting moderation. Thank you for participating in the discussion.
What is the difference between architecture and design ?
In my mind, a developer is not only a coder but also a designer. The architecture + specfications are inputs for his design.
Re: Architecture Vs Design
by Gary Duzan,
Your message is awaiting moderation. Thank you for participating in the discussion.
"What architecture is" is a point of debate, but you can consider architecture to be the subset of design that focuses on the "big things".
Re: Architecture Vs Design
by Wanderson Santos,
Your message is awaiting moderation. Thank you for participating in the discussion.
There's a great article about this difference here:
Investigating architecture and design
www.ibm.com/developerworks/java/library/j-eaed1...
Re: Architecture Vs Design
by Traxx WiF,
Your message is awaiting moderation. Thank you for participating in the discussion.
I agree. Design and Architecture are two different tasks in a project, but in this article, it's a litle bit confusing...
Re: Architecture Vs Design
by Paulo Merson,
Your message is awaiting moderation. Thank you for participating in the discussion.
Architecture is design, but not all design is architectural. But that raises another question: where's the line between architectural design and non-architectural design?
I suggest this great essay titled
"What’s the Difference Between Architecture and Design?".
In any case, when you're architecting/designing a software system, a more relevant question is:
How much design is enough? That is, for each part of the system, when should I stop designing and move on to coding?
Re: Architecture Vs Design
by William Martinez,
Your message is awaiting moderation. Thank you for participating in the discussion.
Well, yes and no. That sentence may be confusing.
I teach design is actually coding using sentences, and coding means making some decisions. The sentences may be of three levels: Strategic, tactical or operational.
- Strategic is actually describing solution as a set of architectural decisions.
- Tactical is describing solution as a local organization of technology influenced elements.
- Operational is describing the solution using executable code.
Thus, taking those architectural decisions is designing, but architecture is something else.
The architecture of a system is a thing, not a process. It is the result of all the designing, from strategic to operational. That is, the real architecture you have it when you have finished the project. And all the code you have there has been written following microdesign (do I use an if or a switch), tactical design (should I use messages in XML or IIOP) or strategic (will this solution use a component orientation or a service orientation).
So, architecture is the result. Architecture definition is proposing some strategic decisions. Architecture administration/construction is managing the solution creation, so the final architecture matches the business needs.
William Martinez Pomares.
Architect's Thoughts
Software Architecture Documentation template
by Srini Penchikala,
Your message is awaiting moderation. Thank you for participating in the discussion.
SEI has published a Software Architecture Documentation template on their Wiki site:
wiki.sei.cmu.edu/sad/index.php/Main_Page
Software Architecture Documentation Template:
wiki.sei.cmu.edu/sad/index.php/Software_Archite...
Re: Architecture Vs Design
by Dan Hestand,
Your message is awaiting moderation. Thank you for participating in the discussion.
I like your approach to teaching design. That really is how design should be understood. There are also connections between each level: how do the decisions made at each level influence or constrain decisions in the other levels? These connections are frequently not well understood or poorly thought out. Taking just the strategic view may lead to designs that are not implementable or lead to implementations that subvert the original intention of the strategic decisions.
I would, however, disagree about architecture not being a process. It is certainly a result, but in my view, the process of architecture is ensuring that all decisions, at all levels conform to the ultimate goal of the software product, namely to deliver value of some sort. For a product development company, this generally means that all strategic design decisions must be made in the context of the overall corporate business strategy. Since this strategy may not be entirely stable or poorly articulated, the "process" of architecture is to continually examine decisions (not just new ones, but historical as well) and understand how those decisions align with the business strategy. For business strategies that are fluid or poorly articulated, relevant architectural decisions must account for this instability.
The architect/system engineer/CTO/CEO work together to ensure that the vision is properly articulated at all levels. To my mind, this is the main purpose of documenting architecture. When the documentation becomes useless or appears irrelevant, these actors should take that as an indicator that a change has occurred at some level and use that as a point to understand that change. Was it organizational thinking, philosophy, was it corporate understanding of strategy, was it a market place shift? And if nothing obvious stands out, it could indicate a development organization that fails to follow guidance and proceeds at its own discretion. Again, the documentation communicates beyond the words contained therein.
My 2cents worth.
Dan Hestand
Re: Architecture Vs Design
by William Martinez,
Your message is awaiting moderation. Thank you for participating in the discussion.
Hello Dan.
Agree. Let me explain about the "process".
Architecture has been though as a method, a process, a document, or even a discipline. But to be clear, the architecture of a system is the end result, the organization of elements and their interactions, taken from the live application, not from paper.
The architecture definition (which is stating the initial strategical design), is a short process. Then you have to build your system, that is the Architecture administration/construction, which is also a process. So, architecture is a thing, creating the architecture is a set of process. Hope that clarifies.
Now, about:
Correct. I mention that as a vertical, in-deep review. There is a process where design is matched against architectural decisions, and code matched against design, and anything that does not fit is analyzed to find why it was created like that. You can then adjust down, or up, in case the architectural decision appears flawed when constructed.
Again, one important part of that documentation is the rationale of decisions. When you do the peer review, and you see that the code does something different, you may go and ask why? Then check against design and find the why of the design, and the why of the architecture. There you have very good info to actually decide if you change the code or you change the architecture decision. More important indeed, you actually know that something was not created as initially defined, which is not common.
William Martinez Pomares