How to take the Pain out of Architecture Documentation

If you start a conversation with an engineer by saying “We need to write the architecture documentation,” your best case is eye-rolling and deep sighs, and your worst case is they just turn and walk out of the room. That is how painful architecture documentation can be.

Some might debate whether it’s more painful to “not to have any documentation at all” vs. “having it but it’s constantly out-of-date,” however, the best practice is to have it.

A well-documented architecture can be the difference between a project that succeeds and one that fails. Not only does architecture documentation ensure that a system is well-understood, thoughtfully designed, and can be clearly communicated to others, but it also results in higher team productivity, a better onboarding experience, and great software.

Software architecture without documentation is incomplete

Have you ever encountered a developer who is happy with a lack of documentation (in any of its forms)? After all, there is a reason why the expression “when code is written, only God and the programmer understand it. Six months later, only God” is so popular.

Software architecture documentation is a guide to the structure of your software, and it has many purposes:

• Productivity: It helps developers, architects, and other stakeholders understand how different components of the system interact with each other, identify potential issues, and make informed decisions about future development.
• Collaboration: It unites everybody around a common understanding of how a system will work and what the final outcome will be by presenting all the key details clearly to all the stakeholders.
• Consistency: It defines a shared language and best practices. In a large organization, where multiple teams may be working on different components of a distributed system, having a well-documented architecture can help ensure consistency, reduce the risk of errors, and facilitate compliance with industry standards and regulatory requirements.
• Onboarding: It makes it easier to educate newcomers to the system so they can grasp how it works and use it as a reference while working to build out, expand, or fix the software. In fact, lack of documentation is one of the main reasons why onboarding to a new team can be painful or unsuccessful.

Ultimately, it’s a very powerful set of documents: it can elevate a team’s productivity and raise the quality of the final software.

Why is it so painful?

In simple terms, you need a significant and ongoing investment in time and effort to ensure that the documentation is accurate, up-to-date, and comprehensive.

Here’s why:

(1) Additional overhead for developers. Generally, developers are encouraged to document their decisions and their code, as they work. However, not only is this time-consuming, it’s an unpredictable amount of work: the amount of time it takes can vary depending on various factors (including the complexity of the code, the level of detail required, the developer's experience with documentation, and the company’s documentation standards). Ultimately, the temptation to “postpone” documentation is very hard to resist, especially when you have a deadline to meet.

(2) Software architectures are getting more and more complex. With the rise of distributed systems, the number of components, services, and technologies that interact with each other has increased exponentially. Just think that the average company in 2022 was using over 88 different web apps (source →). Capturing all that complexity in one place, with all the needed information to be useful (e.g. versions, dependencies, etc.) can be challenging.

(3) Systems are often dynamic and constantly evolving. Companies are changing at a faster pace than ever to keep up with disruptive technologies, organizational changes, economic shifts, etc. Not only that but in a distributed system, changes to one component can have a cascading effect on the entire system, making it necessary to update a whole host of documents. As it’s mentioned in this paper: “Real-world Enterprise Architecture changes too quickly to synchronize to an Enterprise Architecture model”.

(4) No new standards have evolved to fully replace the traditional approach. The role of a traditional software architect, who is responsible for creating structured architecture documentation (such as UML) is in decline. Likewise, traditional documentation-heavy approaches (e.g. lengthy architecture blueprinting, target state development, etc.) are being abandoned because they are counter to agile principles.

When no one person is responsible for the upkeep of documentation, developers have a host of tools they could use to do it themselves, however, none of them provide a complete solution: they either capture a specific area (e.g. code / API architecture) or lack critical functionalities (e.g. they are a static image of the platform architecture that doesn’t update automatically in real-time).

What does good look like?

While some of these characteristics are more critical than others, all are needed.

• Real-time - It’s a dynamic source of truth for the full architecture of the system, including the architectural debt. Any stakeholder can rely on it implicitly, without worrying about outdated and misleading information.
• Automatic - It is automatically generated and updated: it’s embedded in the development process and no longer a “catch-up activity” for developers. Should a team member leave the organization, no knowledge would be lost with them.
• Thorough - It captures all architecture decisions from the very start (i.e. why a system and its components were designed a certain way). You can look back and verify that the solutions continue to meet business needs and have the necessary context when extending or refactoring them.
• Accessible - Some may argue that the code itself is all the documentation you need, but code alone doesn’t provide context for decision-making, and it’s not accessible for non-technical stakeholders. Your documentation should also be easy to consume by people with disabilities (e.g. a visual impairment or another difference in ability).
• Consistent - It uses consistent visual and written language, where all the terms are defined and used in the same way throughout your documentation.
• Interactive - Architectures and corresponding designs can be fluid especially when testing new capabilities, when in pilot mode, or building a new system. The development team needs to have a way to sketch how an addition to the architecture would look and track which are “transient” vs “permanent” elements.
• Contextual - Not everyone needs to know every single detail of a big and complex distributed system. You need to be able to limit (or extend) visibility according to each developer or team’s needs. For example, business executives don’t need to see the technical details, while engineers cannot work effectively without them.

The solution: visual collaboration + automation

We have tried many solutions over the years to ‘cure the pain’.

Developers have been encouraged to write the documentation themselves. This, however, inherently collides with their aspirations: they see themselves as builders, engineers, scientists - asking them to focus on a “boring and less exciting” task like going back to document everything, is like asking them to stop building new bridges and go paint old ones.

What if we had a dedicated technical writer? Good solution… only now you have a writer chasing the engineers to understand what changes were made and why, which docs need to be updated, etc.

Ok, but what if we build it directly into the development cycle and engineers have to write the documentation to complete a project? Sure [said in an ironic voice]. I’m certain that the task to ‘Write / Update documentation’ will not land at the back of the queue and everyone will jump on it enthusiastically.

Once you solve the problem of who writes the architectural documentation, you can leverage some very effective approaches like arc42 template, C4 model, UML, ArchiMate, etc.

But how do we solve the who problem?

The dev tools industry is currently being swept by innovative technologies that leverage visual collaboration software, automation, and AI. Developers are enabled so they can focus on design, writing software, and collaboration - in other words, to focus on “building”.

That is why Multiplayer is working on a solution that combines these exact technologies to help backend developers easily visualize and collaborate on distributed software, which would not only provide a real-time, dynamic visual representation of the system but would also automatically generate all the needed documentation.

Can we make architecture documentation painless for you? You can find out for yourself by signing up for free now.