Freedom to decide, responsibility to explain - How and why to automate your architecture docs

As we work, we all play two roles. Firstly, there is the “expert” role. We play this role when we are working in code that we personally designed and wrote. We know how it works, and we are the go-to source for questions. Secondly, there is the “newcomer” role. We play this role when we enter areas of the code that are unfamiliar.

When we work as experts, we decide. 
When we are newcomers, we encounter the decisions of others. 

In the “expert” role, we have a lot of freedom to choose the architecture of our software. Like any freedom, this freedom comes with responsibility. In this case, the freedom to decide implies responsibility to record our decisions and explain our choices to others. As we decide, we must create resources to assist the newcomers to learn, understand, analyze, modify, and optimize the choices that we made.

The responsibility of “choice” is one that developers enjoy. But the responsibility to “explain” (and document) has always been, and remains, a struggle. Want proof?

At AppLand, we’ve been conducting a survey on the “State of Software Architecture Quality.” In our survey, only 12% of respondents agree that their design documentation is “frequently updated and accurate.” But 84% agreed that “a system which provides up-to-date diagrams and visualizations of code structure and end-to-end data flows would be useful.” That’s a large, important gap.

What kind of architecture information do developers really want?

So what does successful architecture documentation, for the purposes of learning and analysis, look like? There are many important situations in which software developers want up-to-date architecture documentation. Including:

• Onboarding to new code
• Troubleshooting
• Refactoring
• Design reviews
• Security and compliance audits
• Establishing uniform standards, to cut down on needless variation.

However, traditional architecture docs, like UML, aren’t good at helping teams to understand and improve existing software. If they were intended to be useful as analysis tools, they’ve failed at that.

Why? In order to be useful for code understanding and analysis, architecture documentation needs to be better in four key ways.

1. It needs to be up-to-date. Wrong documentation is worse than useless -- it’s misleading. I may as well just go straight to the code and slog it out.
2. It needs to be interactive. A static picture, drawn using a scheme that was designed to be printed out on paper, is not powerful enough.
3. It needs to be contextual. Traditional architecture documents are too big and too complex. Once focused on a specific use case, documentation becomes much more useful. This is why StackOverflow and developer blogs are so popular.
4. It needs to be as close to the code as possible. Ideally, it’s in the code. The code is the work, the code is the truth, and that’s where all assistive and supporting information needs to be.

AppMap - What auto-generated documentation can be

How can architecture documentation be kept up-to-date?

There aren’t many universal truths in software development, but here’s one:

Architecture documents and diagrams are always out of date. 

With the decline of the software architect role in the software industry, there’s also been a decline in structured architecture documentation (such as UML). Overall, this is fine! because, no matter who you talk to -- from the smallest shop to the biggest FAANG developers -- architecture documentation is never up-to-date. It wasn’t kept up-to-date by architects and it’s not being kept up-to-date by developers, either. Nothing has changed there.

So what’s the right way for developers to create documentation that’s always up-to-date? Fortunately, there’s a very clear answer to this question. Developers have spoken loudly and clearly about the way we want to work, and there are two great points of consensus:

1. The code is the source of truth.
2. Code is maintained through a standardized workflow.

The developer workflow (2) has been standardized and optimized to great effect. It looks roughly like this:

1. Choose a task
2. Develop in a local environment
   1. Design
   2. Code
   3. Test
   4. Iterate back to step (a), as needed
3. Push code to the source code management (SCM) server
4. Run automated tests and other automated quality checks
5. Perform code review
6. Iterate back to step (2), as needed
7. Publish artifacts
8. Deploy artifacts to production

Processes that don’t fit into this workflow have been obsoleted and discarded. To get developer buy-in, all work must be channeled through this process, including improvements to the process itself (e.g., building and updating infrastructure). Of course, this is an idealized view. But the winning organizations are the ones running this process in its most pure fashion.

So, in addressing architecture documentation, the questions can only be: Where in this continuous, agile development process can those documents be created, updated and vetted? And how can it be done using code?

What does a developer-friendly solution look like?

In AppLand’s State of Software Architecture Quality survey, 84% of respondents said that “a system which provides up-to-date diagrams and visualizations of code structure and end-to-end data flows would be useful.”

Yet, only 19% said that they are using architecture visualization tools such as Lattix, CodeScene, Structurizr and PlantUML. Regarding this crop of tools, 59% said, “We don’t use them and don’t intend to use them.” That’s a strong signal that new approaches are needed.

92% agreed with, “Developers have the resources that they need to produce quality code.”

So, take these statements together:

• 84% of developers would like to have up-to-date diagrams and visualizations of code structure, and end-to-end data flows, but don’t have that capability today.
• 92% agreed that their team has the resources they need to produce quality code.
• Only 19% use existing code / architecture visualization tools, and would like to keep using them.

The problem is not a lack of awareness of current available approaches. Developers want better options. We want higher value architecture visualizations that are more powerful, can be created through the standard development process, and can be used to actually make architecture better.

What’s coming next?

At AppLand, our mission is to modernize the way that developers learn about, analyze, and improve architecture. We do this by collecting interactive architecture and code behavior data automatically, analyzing it, and presenting it visually and interactively.

We have three primary aims:

1. Close the gap between those 84% of developers who want access to up-to-date architecture information, and the 12% who have it today.
2. Modernize the presentation of architecture information.
3. Automate the generation of architecture information, so that stays up-to-date. Because automation is the only way that this goal can be achieved.

We have a lot of work to do to meet these goals, but we’ve achieved a lot already. So, in the remainder of this series, I’ll share our approaches with you, and talk about our plans for the future.