Documenting Architecture

Documenting architecture is an important part of software development. Architecture must be documented in a good amount of detail and should be presented in an accessible form for many different stakeholders. A simple search shows lots of material. However, much of it tends to be pretty complex in nature. Much like there is not one definition around what an architect does, there is not one standard precise way of documenting architecture. The goal of this post is to share some of the techniques that I have successfully used as easy-to-read material, as well as to solicit feedback.

Reasons to Document Architecture

Let's look at some of the reasons around why we need to document architecture.

• Whiteboard designs are not persistent!
• Teams grow in size, and explaining the principles of architecture to a wider and wider audience gets difficult.
• The various decisions that drive the design could be forgotten and documenting them could help us get some rationale.
• People don’t stay forever.
• Stakeholders have different concerns. This is a solid way to address those concerns ahead of time.
• This is an easy tool to visualize and plan for many different needs.
• Distributed systems and approaches like SOA have increased the overall design scope and complexity. No longer is the idea of a single system or a monolith accomplishing all the needs. Invariably, any modern system is build using multiple components and systems, and the interaction of these components together is what collectively accomplishes the business task. It becomes important to document their interaction.

There are many more reasons and based on your experience; you've probably experienced some or many of those reasons.

These reasons pose several different questions:

• What should we document?
• How do we document?
• What approach or view should we use?
• How do we communicate clearly?

This article will attempt to answer some of these. However, the key point to remember is that there is not one right or wrong way; the answer depends on different things. It is important to consistently and periodically review and correct.

Another related question that could drive some of these concerns is the role of the architect. There are different views, ranging from the extremes of the architect being totally disconnected from the technology to architects who are totally immersed in technology working on bleeding edge research. The reality tends to be in the middle, where the architect is still expected to be technical and equipped to have skills to converse with non-technical stakeholders.

Documentation Misnomers

Let us first start with the misnomers that seem to be common:

• There are architects who specialize in particular diagramming tools or diagrams. They get so excited in the process of creating these artifacts that all their time and effort is spent focused on producing more and more diagrams. These are the architects whom sometimes I refer funnily as enterprise artists rather than enterprise architects. We have to remember that these diagrams are means to an end and not the end itself. There is nothing wrong in being artistic, but we are not here to produce art but architecture! It’s important to balance out the artistic urge and its okay for some of the diagrams to be less perfect in terms of coloring, shapes, etc.
• Similarly, there are another set of Architects who use all sort of complex Architecture Artifacts that’s available in the industry. They simply love complexity and would like to talk things in abstract and enjoy the kind of hallow the mystery produces.

"Any intelligent fool can make things bigger and more complex... It takes a touch of genius - and a lot of courage to move in the opposite direction." (Source.)

However, they have complete disregard for any feedback on whether what they produce is useful to any stakeholders. 

It’s important to remember that doing actual architecture and addressing concerns of the stakeholders is the primary role of an architect and the tools and documentation play more of a support role that helps us accomplish the primary role. So, picking tools and techniques that would allow the architect focus on his or her primary job is important. Any tool that is over-engineered or makes people spend more time is an absolute no for me.

Many architects are convinced that documenting views alone is sufficient. The industry has come to accept that software architecture cannot be described in a simple one-dimensional model. There are multiple goals and stakeholders and there are different views to address the goals and concerns. Architecture views are representations of the overall architecture that are meaningful to one or more stakeholders in the system. The architect chooses and develops a set of views that will enable the architecture to be communicated to and understood by all the stakeholders and enable them to verify that the system will address their concerns. Documenting more than views including things like architecture decisions, quality attributes, etc. are also equally important.

The views could be produced using different levels of notations. It is not a rule of thumb that they always need to be produced only using formal notations.

• Informal notations: custom conventions (i.e., general diagramming tools).
• Semi-formal notations: some element of semantics (i.e., UML).
• Formal notations: precise semantics (i.e., ADL such as ArchiMate).

More formal notations tend to take more time but allow us to produce less ambiguous artifacts.

So, what should a good architecture document contain. There are no definite set of rules and these are some of the suggestions that make sense to me.

Scope and Summary

I believe any document should include an introductory session that introduces the architecture to the audience. We cannot expect the readers of the document to always have all the details. In a good introductory segment, I would include:

• Purpose.

• Stakeholders.

• Motivation and concerns.

• What is covered and not covered.

• Current as is architecture.

Identify Stakeholders 

We should know who is interested in the architecture, understand what is important to them and should come up with an architecture that should be reflective of their different needs. These are the very same stake holders who would consume many of the Architecture Artifacts. So, It is important to identify the key stakeholders and discuss with them regarding what they expect from the Architecture and related Documents. 

Important activities include

• Identifying the stakeholders.
• Understand and document their motivations that could impact architecture.
• Understand expectations from the architecture documentation.
• Decide how we would address their concerns (identify ViewPoints).
• Agree on what you would produce.
• Get early feedback.

Producing a document that is nowhere referred or that makes people struggle to find the information is as good as not producing the documents.

Identify Views

Here is a definition of architecture view from OpenGroup:

"Architecture views are representations of the overall architecture that are meaningful to one or more stakeholders in the system. The architect chooses and develops a set of views that will enable the architecture to be communicated to, and understood by, all the stakeholders, and enable them to verify that the system will address their concerns."

Overall, we have come to a common understanding that describing architecture in a one-dimensional model is pretty complex to represent as well as understand. One-dimensional models are usually hard to understand and hard to maintain and end up being very poor in satisfying all of the different Stakeholder's concerns. Just like how traditional engineering produces different diagrams (Ex: Floor Plans, Electricity, Security), the IT Architect is also expected to produce different views to address the concerns of the StakeHolders. The approach of producing many different Views allows us to represent complex systems in a manageable and maintainable fashion and satisfies many of the concerns of business and technical stakeholders. 

There are different approaches that support this concept and are listed below. In general, the idea is to separate and provide views that support the following or more in detail. There are different nomenclatures available and I am using what I see to be the best fits.

• Module views: Internal working of a component.

• Logical views: How different modules work together to provide the business functionality.

• Physical views: How the components are deployed.

• Behavior view: The dynamic aspects of the system behavior and the variations. While the views are concerned with the structure of the system, these views focus on the behavior of the system for various internal and external stimuli and other behavior-driven inputs.  

Example View Methodologies

• Krutchen 4+1 Architectural View Point.

• Siemen's Four View Model.

• Rozanski Woods.

• Archimate View Points.

• UML 2.o.

It is important to also document which Views address which of our stakeholder concerns to allow stakeholders to focus on what is important for them. Also there are different tooling avalaible to satisfy the different Views, each satisfying a variety of concerns. It would be a good idea to identify and decide on them across the spectrum to ensure consistency.  

Document Interfaces

The many different elements that make up the System interact with each other through interfaces.  They are the key to building the Systems and are important for many stakeholders like Developers, Testers, operational folks etc. The interface documentation should inform what the consumers should know to interact with it in combination with many other elements. Usually the interfaces tend to be documented along with the Module Views as a part of the Views. The interface documentation is not just limited to the REST or SOAP API documentation. Though they could be classified as interface documentation and could be produced using some of the standard tooling available, they very well could be a Java or a C# Interface.

These are some of the suggestions around organizing interfaces.

•  Name and version the interface.

• Provide details of operations and their semantics

• Provide what variances are available with respect to consuming the interface.

• Provide expected error conditions and error handling details.

• Provide performance or reliability numbers.

• Provide behavior diagrams like "sequence diagrams" in case the interaction is complex.  

Document Key Decisions

A key responsibility of the Architect is to make variety of decisions weighing in the different concerns and tradeoffs. The approach of understanding software architecture in terms of a variety of architecture decisions is widely recognized. The decisions if documented could help in the long term around why certain design decisions were made and the actual thinking behind these decisions. A simple approach is to maintain a collection of "architecturally significant" decisions in a decision log. These are the decisions that impact many of the architecture concerns like NFRs, interfaces, Implementation Concerns, Design etc. The decision log could include things like

• Context or background. Explain what the issue is about and the options that are available.

• Decision. This includes the decision that is taken and the rationale.

• Status. This involves whether the decision is proposed or accepted. There are various lifecycle events for a decision.

• Impact. What is the impact of the decision? What do we gain or lose? What are the tradeoffs?

• Stakeholders. Parties who are impacted by decisions.

Document NFRs and Quality Attributes

This involves software that does not address its quality concerns and won't meet needs. It is important to document the different quality attributes and other NFRs.

• The design approach should consider the nonfunctional requirements and related cost.

• Various factors like like performance compliance, PCI and governance requirements, etc. that impact the design are visible to the different stakeholders.

• Different architectural components providing a service have quality attributes defined in their interface documentation. They, in turn, depend on all requirements.

• The NFRs should show how different nonfunctional requirements are satisfied.

• It helps different stakeholders like quality engineers and operational engineers to plan in advance various tasks like load testing, operational alerts, etc.

Standard Templates

Use some sort of standard templating around how the architecture document should be produced. This would ensure consistency, even, if the documents are produced by different architects and bring in familiarity, to the document readers. Also, this would pave way for the documentation to be easily referred.

These are just an example and you should come up with a template that is truly representative of what your architecture team does.

Review Documentation

Adopt a formal documentation review process. The documentation is going to serve as the communication channel and it is imperative that we have a formal process not just to review the architecture but also the document supported by the architecture.

Conclusion

Documenting architecture is a pretty complex task and there has been great amount of research and discussions happening for many years. Hope this page gives a good easy to read introduction, largely abstracting many of the complexities.

References
http://www.sei.cmu.edu/architecture/tools/document/viewsandbeyond.cfm x
http://www.viewpoints-and-perspectives.info/home/book/ x
https://www.amazon.com/Documenting-Software-Architectures-Views-Beyond/dp/0321552687 x
http://www.viewpoints-and-perspectives.info/ x
http://www.mit.edu/~richh/writings/doc-framework-decisions.pdf x
http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions x