What is Software Architecture Documentation? In simple terms, architecture is the design and structure of your product. The purpose of writing or reviewing software architecture documentation is to review or communicate the plan for various components of a software system, their characteristics, and the relationship between them.
A Brief Introduction to Software Architecture Documentation One of the most known forms of software architecture is the software development architecture. The process includes planning, designing and managing the development of the software product. The workflow associated with architecture spans from the initiation to termination of a software development life cycle. The primary benefit of the architecture design approach lies in incorporating quality early in the life cycle of the engineering process.
Software architecture documentation can be of immense help for project team members. If used in the right way, it can assist in keeping track of all the software assets, their relation to each other, and give a thorough insight into the software structure. However, it is a science on its own: there are quite a few best practices that are applied when creating software architecture documentation. We will discuss these in the article.
Are you curious about best software architecture documentation? Or about software architecture documentation best practices? If this is the case then keep reading (I assure you that these are things that you should be very interested in). Perhaps it’s just a matter of semantics and maybe I’m being driven by the need to bring structure to my writing, but for me there is a clear dividing line between software architecture and software development. Fundamentally, it comes down to why are we building this application. On one side we have business applications, on the other side we have infrastructure applications. Yes, there is a lot of overlap and if this discussion was any more detailed we would probably get into specific communication patterns, but for now I’m going to leave that aside.
No one standard for documenting software…
When we think about API documentation, the most obvious answer is OpenAPI / Swagger. Sadly, it is not as easy when we talk about architecture.
In reality, there are many standards for a software architecture document. One software architect will use UML for that, another will take a completely different approach. However, there is always one thing in common (of course). Architecture documentation takes more than a single diagram type to be complete in any use case.
Because of that, it is good to have more possible tools we can choose from. That’s why at The Software House we decided to go with a combination of:
- high-level architecture diagram (C4),
- database schema diagram (ERD),
- flowchart diagram,
- sequence diagram.
Obviously, we rarely use all of them at once – it depends on the architectural system we’re designing – but our minimum is to have a C4 diagram.
What is C4?
C4 is a model that is the closest to be called an architecture documentation standard. It is a set of 3 main and 1 optional diagram:
- context
- container
- component
- code
Each diagram focuses on a specific detail level. The more we get into the details, the more often we need to update that diagram. That’s why for some of them, the key is to generate those instead of creating them manually.
Let’s imagine we’re in the development of an invoicing system for our company. The main users are going to be accountants and we need to integrate it with our internal user management, project management systems, and Slack.
The first diagram we need to create is a Context Diagram
Context Diagram
It is all about the big picture. We don’t need to know the technical details here. What is important for us are people (actors, who are using the system) and software systems that are part of a business solution.
Context is a diagram that we would show a business person explaining what kind of a system we’re building, what integrations it has, and who is going to use it.
With our invoicing system, it could look like this.
Container Diagram
The second level is a Container Diagram. This time, our focus is on separately running/deployable parts of our system. We could compare it to Docker containers.
Each separate service/database/storage is a separate container on that diagram.
Let’s go back to our Invoicing System. It will have an API, a Frontend, a database, but also a caching layer and file storage. Each of those will be a separate container.
What is important on this level is to describe the technology that is used for that specific container and also how communication between the containers looks like. Is it HTTP? Or maybe is it gRPC? That information needs to be on a diagram.
As you can see, we have much more technical information on this diagram. We can see what type of storage we use, what technologies are used for frontend and backend software development, and how those two systems communicate with each other. We can also see all the integrations between specific containers and external services, yet we know nothing about the actual implementation.
This is what the next diagram is about.
Component Diagram
On this level, we are going to focus on the major building blocks of a specific container. This is where much more implementation details are going to be visible.
Services, repositories, command handlers, external services clients and even endpoints – all of those might be put into this diagram. What is important is to show not only the building blocks but also the communication/relationship between these.
So what would it look like in our Invoicing System? Let’s focus on Invoicing API. The main components are going to be different command handlers, clients to communicate with Keycloak, and Slack. We would also need a few repositories, a PDF management service, and webhook integration for JIRA.
Let’s see that on a diagram.
As you can see, a component diagram is not about putting every implementation detail, but focusing on those that are the most important. At The Software House, we also follow a few rules:
- every arrow needs to have a description,
- every name we use needs to be a name that is used in a code (basically when we call something a PDF Generator, there needs to be a thing in the code for that),
- every endpoint/way of communication needs to be visible,
- every color has a meaning (usually we also add a legend for that).
Those simple rules make it easier to follow and design new diagrams since everyone in a company does it in the same way.
Code Diagram
The last diagram that is part of a C4 family is a Code Diagram. This is the one that will be updated the most often, but also is the optional one. At TSH, we don’t really use this diagram. However, the key here is to generate it from the code itself.
It isn’t as hard as it might sound. In reality, we might use some annotations/documentation properties to generate a pretty good UML class diagram that will describe our code and how everything is connected with each other.
A good example of a class diagram could be:
Image source: uml-diagrams.org
It goes so much into the details that with every pull request it will look different, that’s why there is no way to create those manually.
Agile and waterfall approaches
The documentation types that the team produces and its scope depending on the software development approach that was chosen. There are two main ones: agile and waterfall. Each is unique in terms of accompanying documentation.
The Waterfall approach is a linear method with distinct goals for each development phase. Teams that use waterfall spend a reasonable amount of time on product planning in the early stages of the project. They create an extensive overview of the main goals and objectives and plan what the working process will look like. Waterfall teams strive to create detailed documentation before any of the engineering stages begin. Careful planning works well for projects with little to no changes in progress as it allows for precise budgeting and time estimates. However, waterfall planning has proven to be ineffective for long-term development as it doesn’t account for possible changes and contingencies on the go. According to KPMG Global Agile Survey, 81% of companies initiated their Agile transformation in the last three years.
The agile approach is based on teamwork, close collaboration with customers and stakeholders, flexibility, and ability to quickly respond to changes. The basic building blocks of agile development are iterations; each one of them includes planning, analysis, design, development, and testing. The agile method doesn’t require comprehensive documentation at the beginning. Managers don’t need to plan much in advance because things can change as the project evolves. This allows for just-in-time planning. As one of the Agile Manifesto values suggests, putting – “working software over comprehensive documentation -“, the idea is to produce documentation with information that is essential to move forward, when it makes the most sense.
Today, agile is the most common practice in software development, so we’ll focus on documentation practices related to this method
What’s next?
C4 is a relatively simple model to describe your architecture. There is a pretty good benefit of using such an approach – the whole system is easier to understand, making onboarding of new developers faster and easier.
By using C4 everyone can understand the system to the level that is useful for them. Not everyone needs to know about implementation details, however, everyone should be able to understand the high-level goals of a system and what services are used to make it work.
Obviously, C4 is not the answer to everything. In a more complex system, we would need additional types of diagrams – ERD, sequence, flowcharts, etc. However, C4 is an excellent starting point.
Types of documentation
The main goal of effective documentation is to ensure that developers and stakeholders are headed in the same direction to accomplish the objectives of the project. To achieve them, plenty of documentation types exist.
Adhering to the following classifications.
Software documentation most commonly used in Agile projects
All software documentation can be divided into two main categories:
- Product documentation
- Process documentation
Product documentation describes the product that is being developed and provides instructions on how to perform various tasks with it. In general, product documentation includes requirements, tech specifications, business logic, and manuals. There are two main types of product documentation:
- System documentation represents documents that describe the system itself and its parts. It includes requirements documents, design decisions, architecture descriptions, program source code, and FAQs.
- User documentation covers manuals that are mainly prepared for end-users of the product and system administrators. User documentation includes tutorials, user guides, troubleshooting manuals, installation, and reference manuals.
Process documentation represents all documents produced during development and maintenance that describe… well, the process. The common examples of process-related documents are standards, project documentation, such as project plans, test schedules, reports, meeting notes, or even business correspondence.
The main difference between process and product documentation is that the first one records the process of development and the second one describes the product that is being developed.
Product: System documentation
System documentation provides an overview of the system and helps engineers and stakeholders understand the underlying technology. It usually consists of the requirements document, architecture design, source code, validation docs, verification and testing info, and a maintenance or help guide. It’s worth emphasizing that this list isn’t exhaustive. So, let’s have a look at the details of the main types.
Product requirement document
A product requirement document or PRD provides information about system functionality. Generally, requirements are the statements of what a system should do. It contains business rules, user stories, use cases, etc. This document should be clear and shouldn’t be an extensive and solid wall of text. It should contain enough to outline the product’s purpose, its features, functionalities, maintenance, and behavior.
The best practice is to write a requirement document using a single, consistent template that all team members adhere to. The one web-page form will help you keep the document concise and save the time spent on accessing the information. Here’s a look at an example of a one-web-page product-requirements document to understand various elements that should be included in your PRD. Nevertheless, you should remember that this isn’t the one and only way to compile this document.
Conclusion
Architecture refers to the concern about organization of details of the software application. It is not about a single element; it is about the combination of elements and the organization of these elements. As such, it influences all stages of software development and maintenance.
Documentation is one of those things that is important, and sometimes frustrating. We’ve all had those days where you feel like you have written and re-written a feature or requirement to the point it barely resembles what you started with. You step back and look at your work, and realize that no matter how long you spend writing it, you won’t make anyone understand what this requirement is, or why it should be done a certain way unless they have to have an in-depth knowledge of how everything fits together. This is your chance to explain something that maybe even you are not completely sure how it works under the hood.