An overview of software architecture documentation
Let us start with a common thing. After a long day, you recognize you don’t have any food for dinner at home. Your favorite meal is spaghetti with pesto and you realize you need to buy some other things as well. Then you went to the nearest supermarket and bought a lot of stuff. At home, you realize that you forgot to buy pesto. That’s frustrating, nobody wants to eat dry spaghetti.
What this example displays are the importance of documentation. This is a really simple example but it is the same basic principle.
If it is not written down, it does not exist | Philippe Kruchten
But we don’t focus on the spaghetti documentation in this article we concentrate on the documentation in terms of software architecture.
In this article, we will cover the following topics:
- What is software documentation?
- Stakeholders for software documentation
- What are views & notations? Which are important?
- Define and compare architecture description languages
- Open-source systems for software documentation
- Summary and outlook
So put distraction potential away get a cup of tea or coffee and let us start!
1. What is software architecture?
Let us try to focus on our initial goal of this work and start talking about software architecture documentation in detail. To get to this point we need to define what software architecture is. Since we are in the IT bubble there are lots and lots of definitions for the same thing.
Over the past decade, software architecture has received increasing attention as an important subfield of software engineering.¹ Of course, this is depending on the numerous innovations in IT. These innovations led to the status quo in which almost every single company in the world uses such software. Companies use software to achieve their business goals. To create and maintain software that meets the desired business goals software architecture is needed. The well-documented software architecture allows us to overcome the gap between IT professionals and business analysts. Because of this huge gap, software architecture is a critical component of whether the software will be useful or not. Good architecture can help ensure that a system will satisfy key requirements in such areas as performance, reliability, portability, scalability, and interoperability. Bad architecture can be disastrous.¹
Nevertheless, we want to give you one definition of software architecture that hopefully, we all can agree on:
Software architecture can be described as a set of structures needed to reason about a system, which comprises software elements, relations among them, and properties of both.²
This basic definition should be enough to continue with this article. But you must keep in mind that there is no such thing as THE software architecture. Software systems are composed of many structures and no single structure holds claim to being the one and only software architecture. Depending on your specific needs there are a lot of different architectures that are designed to answer your questions.
What is software architecture documentation?
So, we looked at what software architecture is and now we want to focus on the documentation. Documentation is often associated with annoying questions from the project lead or customers. Some might say “I’ll write it at the end of the project because no one reads it!” You might be right, but you will miss the key role of a design doc.³ Documented knowledge is expressed in natural language and/or images, while formal knowledge is expressed in formal languages or models with clearly specified semantics (e.g. ADL’s, Domain models, etc.).⁴ We will focus on ways to document knowledge later in this article.
Software architecture documentation allows us to support the work of everyone in the project: developers, deployers, testers, and analysts. The guidance provided by well-written documentation helps the architect to reason about the architecture design and communicate it while the architecting is still in progress. It is possible to capture decisions and communicate them whether it’s in a six-month design phase or a six-day agile sprint.
Decisions are made every day. Some are big, some small. In most architecture development processes, decisions aren’t documented explicitly but are implicit in the models the architect builds. Architects make structuring decisions, such as choosing patterns, in the component (logical) model, and deployment decisions, such as choosing runtime patterns, in the physical model. However, stakeholders such as developers, customers, and even other architects do not have the energy to pore through architectural views to understand the architecture. Developers want clear, decisive guidance on how to proceed with a design. Customers want a clear understanding of the environmental changes that must occur and assurance that the architecture meets their business needs. Other architects want a clear, salient understanding of the architecture’s key aspects, including the rationale and options the original architect considered.⁵
So, in reality, well-written documentation is speaking for the architect. It is speaking for the architect when the architect is busy doing his other tasks instead of answering hundreds of questions from various people that are involved in the project. And it also speaks for the architect when he or she has left the project or company and someone else is in charge to answer these questions.²
At this point, you should have a general understanding of why documentation is such a critical component in software projects. Now we want to focus on some challenges of documenting⁴:
- Understandability — Documentation always looses some of the intentions of the author when someone else reads it. As the size of documentation increases when systems become larger and more complex, the understandability of the documents becomes more challenging. Especially when stakeholders have different backgrounds, the language and concepts used to describe the architecture might not be understandable to everyone.
- Locating relevant architectural knowledge — Finding relevant architectural knowledge in (large) software architecture documentation is often difficult. The knowledge needed is often spread around multiple documents.
- Traceability — Providing traceability between different sources of documentation can be tricky. In practice, the lack of traceability usually occurs between requirements and software architecture documents, since it is often unclear how these documents relate to each other.
- Change impact analysis — It is often necessary to predict the impact of a change on the whole system. Therefore, you should analyze which parts of the architecture are influenced when an architectural decision is made or reconsidered.
- Trust — Architectural documentation is constantly evolving and needs to be kept up to date with changes in the implementation and the requirements. In large and complex systems, changes occur quite often and the cost of updating the architecture document is sometimes too costly. Therefore, the document is quickly rendered outdated and the different stakeholders lose their confidence in the credibility of the information in it.
In summary, we want you to understand that software architecture documentation can not be your last task within the project. Because a lot of different stakeholders need to see the documentation and add their own decisions the documentation needs to be updated incrementally.⁶ Another reason is that software projects are executed under strict constraints of time and budget. Team members are often needed for new projects and committed to these projects early on. There is rarely enough time to document all experiences and knowledge after the project delivery. Small teams might perceive codification of their knowledge less important, according to earlier findings and according to our own experience, this can lead to gaps in knowledge. As knowledge is not transferred seamlessly these gaps can hinder the agility of an organization.⁷
Advantages and disadvantages of documentation
Within this part, we are going to briefly address some of the main advantages and disadvantages of software architecture documentation. We described the reasons why you should document your software architecture and your decisions while the project is still proceeding. We will start by providing you with the main advantages:
- Knowledge sharing — Properly documenting architectural decisions is critical because architects make them in complex environments, and they involve trade-offs. How many times have we looked at architecture and been surprised (or even terrified) by the decisions it was based upon? Our first reaction is to ask several rhetorical questions: “What were these people thinking? Had they never heard of sound principles of good design? Did they think that the system wouldn’t live longer than a month?” Well, okay, maybe a few were inexperienced, short-term thinkers. But most had good intentions and did what seemed right in the moment. The decisions made sense under the circumstances, which cost and schedule constrained. However, looking back, after the dust has settled and the original system designers are long gone, we have no context around these decisions; we have no history. All we can do is shake our heads in disbelief.⁵
- Communication — When compared to document-driven traditional software development, agile software development practices advocate an emphasis on direct communication. This focus is embedded in reoccurring practices such as iterative development, frequent customer involvement, daily stand-up meetings, or team-based effort estimation. During the course of a development project, such routines make work more predictable, support the transfer of knowledge, and ensure communication within the team.⁷ Communication is a key component of a successful project. This is not limited to agile projects. Communication helps to share the ideas of the architect to the developers.
- Analysis — A good software architect or project lead will be analyzing the status quo of the project while it’s still in progress — to do this a documentation is needed.⁸ Analyses can be made for several parts of the project whether it’s about the functionality, the time and budget or to test the user interface. These are just a few examples and there are a lot more. Also, keep in mind that the documentation is needed to evaluate the software architecture when the project is completed.
On the other hand, there are some noticeable disadvantages of documentation:
- Costs — this is probably the most obvious one. Writing good documentation takes time through all phases of the project. You probably want to go ahead and fix the latest bug or code the next module — investing this time in documentation is a pain to most developers. But at this point we want to bring a picture that most of you probably already know:
When we are talking about time and cost in software development you can not ignore this simple triangle. We do not want to go too much into detail here, but documentation takes a lot of time that can not be done by a third person as we described earlier in this article. Buying some extra manpower to develop the software in time often brings problems for the documentation. Different companies use different ways to document their work. If the externally acquired parts are not sufficiently documented you may save time now but you will lose that time in the long run.¹ The result is that you need more time for your work which means the cost is higher. But if you document your work properly the quality of the software is more likely to be satisfying. Cost of fixing bugs instead of taking time to write and document proper code! This brings us to our next disadvantage.
Often done wrong — The most frustrating thing about software architecture documentation is that it is often done incorrectly. We will focus on ways to document your architecture later so you will maybe recognize mistakes in your documentation and get better at it in the future. If the documentation is done wrong or even just bad it will not help the architects to understand and analyze the architecture at all. Like this, a lot of time is wasted which results in high costs and probably a bad quality because potential mistakes cannot be found easily.
2. Stakeholders for software documentation
We highlighted the importance of stakeholders several times. At this point, we would like to get more into detail what stakeholders are, and which stakeholders need to be considered in this context. If you are reading this and you think some stakeholder is missing — let us know in the comments!
We define a stakeholder as a person or organization that has rights, shares, claims, or interests concerning the system or its properties meeting their needs and expectations.⁹
In other words, you should always ask for your stakeholders’ opinions because they are influencing the project anyway. Not asking for their opinion will most likely lead to bad communication and can ruin the whole project. Stakeholders provide opportunities and limitations for the system and are the source of requirements. Keep in mind that stakeholders are often not explicitly identified in the decision-making stage. But as soon as the decision is designed, announced, or implemented, everyone affected by this decision will express their opinion.
Stakeholder types
- Project team — You need to know the team and their skills to design an architecture that the project team can create. Designing a real-time data flow without a single data engineer in your team will probably lead to problems — and even worse documentation.
- Management team — Most of the time your project manager will have more information about your stakeholder’s opinions than you. Listen to their advice.
- Third-party companies — Integrating parts of third-party solutions may be a critical process in your project. Take that into account.
- Supporting team — This team will support your system at one or more stages of its life cycle.
- Customers — Customers are one of the key stakeholders. Developing software without the iterative consideration of the customer needs will lead to a solution nobody needs. Your customers are the people who will pay money for your software. Developing something they do not need because you forgot to ask them is very common but painful and expensive learning.
- Heads and employees of functional units — Another critical stakeholder in practice which is often forgotten in theory. Only because you and your team is developing a great and useful software it does not mean that the heads and employees of functional units are willing to use it. Keep these people informed and show them the benefits of your new software. In many organizations, change management should be considered.
- Top managers of the company — These people are responsible for the company’s profit and success. You should involve them in the project because they are in a position to support or stop the entire project immediately.
- Shareholders and creditors — Very similar to the top managers these stakeholders are very powerful when it comes to high-level decisions. You may want to break down your project and show iterative milestones or prototypes.
3. What are views & notations? Which are important?
Views are an important component of software architecture documentation. We discussed what software architecture is, what documentation is, and the role of stakeholders. Views exist in various complexities and are used by numerous stakeholders. It is not possible to describe an architecture in a simple one-dimensional way, because systems are too complex to understand every aspect of it at once. A view is a representation of a set of system elements and relations among them — not all system elements, but those of a particular type.
For example, a layered view of a system would show elements of type “layer” — that is, it would show the system’s decomposition into layers — and the relations among those layers. A pure layered view would not, however, show the system’s services, or clients and servers, or data model, or any other type of element.²
This example should clarify that we can not name the most important views. Deciding which view is relevant for you depends entirely on your specific goals and stakeholders. These goals and stakeholders determine which views to use and what quality attributes they need at which level of detail. Nevertheless, we want to give you three categories in which you can divide most of the explicit views:
- Module views — This kind of view describes an implementation unit that provides a coherent set of responsibilities. The properties of these views define the most important information associated with the module. Some relevant information for the technical stakeholders may be visibility, revision history, and dependencies on how changes to this module might affect other parts and modules of the system. Modular development does not mean agile engineering but there are noticeable similarities. Module views are commonly mapped to component and connector views.
- Component and connector views — Component-and-connector views show elements that have some runtime presence, such as processes, objects, clients, servers, and data stores. These elements are termed components. Additionally, component-and-connector views include elements of the pathways of interaction, such as communication links and protocols, information flows, and access to shared storage. Such interactions are represented as connectors in C&C views. Sample C&C views are service-oriented architecture (SOA), client-server, or communicating process views.
- Allocation views — Allocation views describe the mapping of software units to elements of an environment in which the software is developed or in which it executes. The environment might be the hardware, the operating environment in which the software is executed, the file systems supporting development or deployment, or the development organization.
We provided a brief understanding of technical views. These views are excellent for guiding and constraining downstream developers whose job it is to implement those structures. To complete this short overview, we need to address quality views since there are more stakeholders than the technical staff within the project. Quality views are formed by extracting the relevant piece of the beforehand described views and packaging them together. Some examples of quality views are:
- A security view — This view can show all of the architectural measures taken to provide security. This may contain UML diagrams (source code layer) and allocation views that show the systems used hardware like databases and servers.
- A communication view — This view can be used to analyze certain kinds of performance and reliability.
- An exception or error-handling view — Within this view potential exceptions and errors can be monitored and described on a technical or business level. The focus on how to handle exceptions from the business side is necessary to provide a useful system.
We showed you some of the most important kinds of views. We do not want to go too much into detail on this one, but we would like to quickly address combined views at this point. To put it in simple words combined views are one way to describe your architecture on a high level so multiple stakeholders with different educational backgrounds can understand them. To create a suitable combined view, we recommend writing down all your identified stakeholders and create a table. Enumerate down the rows and think about what kind of view applies to them. This way, you will be able to save time you would be spending on creating a different view for each stakeholder. This is an easy way to create some knowledge for most people involved in the project. But keep in mind that you will need some more detailed views for your technical stakeholders.
There are a lot of ways to structure the documentation. We would like to present a template for documenting a view of software architecture.²
This template should fit on every view you want to document. In the first part of the template is the primary presentation. In this section are shown the elements and relations in a graphical notation. Out of this section, the reader should get a good overview of the documented part, but often there are just the main and important things displayed. What is important is that you explain some ambiguities that are not that clear from the notation.²
To forget the explanation is one of the most common mistakes. In section two every element is explained. It is important to describe all elements. Furthermore, the relations, attributes, interface, and the behavior of each element will be described. In section three there is a context diagram. It displays how the system or a part of a system relates to his environment. The purpose of a context diagram is to show the scope of a view. In section four the variability guide shows how to exercise any of the variables shown above. The last section five is named rationale. In this section, the aim is to describe why the view is as it is and argue why it is chosen correctly. With the template, you should have a good option to create easily understandable documentation of any view.²
In terms of notations, there are three notations to mention. Notations serve to document the views and differ in their formality.
- Informal notations are the most common and fastest way to explain some views or document elements. The way the elements are displayed is often simplified and need often a additional detailed explanation.²
- Semiformal notations is a graphical standardized notation. But often not all elements can be described completely and you need further explanations. Additionally, you will need extra software for most cases.
UML diagrams are semi-formal diagrams. Tools that assist in system design are available and widespread. Later we will recommend one of such a tool in this article. For topics related to software architecture documentation, we recommend this notation.²
- Formal notations are described in a notation that is highly accurate and often mathematically based. In practice, this notation is rarely used. Most programming languages and most logics are formal notations.²
4. Define and compare architecture description languages
Architecture description languages (ADL) are formal languages to represent a software architecture system.¹⁰ ADL focuses on the high-level structure of the overall application, not on a specific implementation. Furthermore, ADL must have simple, understandable, and possibly graphical syntax. The content is about the model components, connectors, and their configurations. Also useful would be tool support for architecture-based development and evolution.¹¹ It is possible that for example, UML can create a diagram out of sourcecode automatically. There are a lot of ADL to choose from. For example, to name a few there is ArTek, Wright, Unicon, Rapide, Archimate. Differences between ADLs are that they can be static or dynamic ADLs. Dynamic ADLs are preferable for quick experiments. The usual procedure is to write, run, fix. In comparison to that static ADLs, it is not that easy to experiment easily. In the static case, the procedure is to write, compile, build, run, fix. The following languages are dynamic ADLs.¹⁰
The Unified Modeling Language (UML) is a standard graphical notation for modeling real-world objects. It is used in particular for the specification, construction, and documentation of software parts and other systems. UML was created for software design and had a tough time to prove oneself. There are some ADL characteristics to be recognized as an ADL. For example, there are rules that an ADL must support the creation of software architecture. Another example is that an ADL must support either an analytical ability, based on information at the architectural level, or a capability for the fast generation of prototype implementations. UML could confirm most criteria points and is now almost everywhere accepted as an ADL.¹²
Yes, the UML is an ADL. The UML is a graphical language for visualizing, specifying, constructing and documenting the artifacts of a software-intensive system |Grady Booch (original developer of UML)
Let us compare the strengths of UML and another ADL language named Archimate. Archimate is a recently emerging ADL. The community of the Archimate is very active and you can get much support in the forum of the open Group (the Publisher from Archimate). It is a lean and simple language. It contains just enough concepts for modeling enterprise architecture and is not bloated to include everything possible. Its uniform structure makes it easy to learn and apply. Archimate ensures consistency across all architecture models. It provides stakeholders with guidance that means that they can design, access, and communicate about any changes and decisions. For changing architecture Archimate provides a framework.¹³
UML has also a good helpful community and provides a graphical framework. UML supports many tools that you can apply and got also the option to multiple views. UML is not suitable for automated analysis of verification and validation etc. of architecture. But on the other hand, supports UML a lot more tools than Archimate.¹²
5. Open-source systems for software documentation
For showcasing we will show you an online UML tool for beginners. Gliffy is an online cloud-based tool available for free. Whether as a plug-in or stand-alone browser version, the software is ideal for teamwork. If you rather want a program or your have some experience in UML designing we recommend Umbrello or if you are willing to pay for a program we suggest MagicDraw.
For example, we used UML for creating a use case diagram of the Apache HTTP Server. Apache is a server that supports concurrency and can, therefore serve a big number of clients. In the following UML-Diagram, you can see an administrator, configuration by files, and server extensions using CGI or the Server API. These extensions (Information processor and provider) can access any resources at the server machine or via a network at any remote machine.
With Gliffy and UML you can create a lot of visualizations for example use case diagrams, sequence diagrams, class diagrams, and so on. In usage, Gliffy is very intuitive. You can drag and drop elements and draw lines between the elements. In the following picture, you see Gliffy in a web browser.
Important is that you choose the program that you are comfortable with so that your ideas can flow more freely and you can enjoy the experience. You can start with your imagination then draw something on a paper and then switch to a program. Another option for software architecture documentation is that you transfer written code into a UML Diagram. In the following, we will show you how to create a UML Diagram out of Visual Studio.
We would like to show you in a simple example of how to create different kinds of UML diagrams when using Microsoft Visual Studio. Go ahead and follow the guide provided here: https://docs.microsoft.com/de-de/visualstudio/ide/class-designer/how-to-add-class-diagrams-to-projects?view=vs-2019
In our example, we were using the open-source project from GitHub: https://github.com/JasonStein/Notepads
Following the Microsoft guide, UML diagrams like in the following picture can be created within a minute.
6. Summary and outlook
Most of the current documentation about the software can be produced automatically nowadays. The software Read the Docs is a free platform for software documentation hosting with freely available source code. It facilitates writing technical documentation by automating building, versioning, and hosting for you. The documentation can be built automatically for the web, print, and offline use. To criticize is the outdated software interface. GenMyModel is a good alternative with a better interface but it is not for free except for some parts.
You almost made it through the entire article! At this point, we would like to summarize the key findings of this article. The first thing to mention is, that there is no such thing as THE software architecture. And just like the architecture, it is not possible to name THE optimal documentation. Documentation should cover the most important information for your specific stakeholders. Identify these and keep the documentation as short as possible without making compromises in quality.
Writing documentation costs time and money but the advantages outweigh the disadvantages. Sharing knowledge with your project team and enabling efficient communication will help you and your team to be successful. Also, keep in mind the different types of stakeholders and listen to them. Many projects have failed because stakeholders have been lost along the road.
We gave you some ideas on views & notations, architectural description languages, and open source systems to create the documentation that you need. Go ahead and take this information to deep dive into software architecture documentation and hopefully improve in whatever your role in your project is. Let us know in the comments if we were able to help you and which part of the article needs revision — thanks!
[1] Software Architecture: a Roadmap
[2] Software Architecture in Practice
[3] Better Software Design Doc will Save the Day
[4] Enriching software architecture documentation
[5] Architecture decisions: Demystifying architecture
[6] Supporting the Collaborative Development of Requirements and Architecture Documentation
[8] Documentation in Software Architecture
[9] Stakeholders in Software Architecture
[10] A Survey of Architecture Description Languages
[11] A Classification and Comparison Framework for Software Architecture Description Languages
[12] Architecture Description Languages (ADLs) vs UML: A Review
[13] Archimatetool
