In no other activity in architecture work does it seem more natural to use Generative AI than in documenting a software solution. It is often seen as a rather unpopular task, the results are usually text-heavy… How convenient it would be if “AI” could make life easier for development teams in this area.
What is it about?
Architecture documentation bridges the gap between requirements and implementation. Traditionally, it consists of collections of texts and diagrams. With the modern Docs-as-Code approach, documentation is treated like source code (“Treat Documentation as Code”). While this changes how documentation is created and maintained, it does not change its core purpose: arc42 structured a Word document back in 2006 – today, it structures a directory tree of Markdown files.
We pursue very different goals with architecture documentation:
• We want guidance and confidence when designing a solution. Documentation supports us in this process, and artifacts such as ADRs (Architecture Decision Records) emerge along the way.
• We want to make the solution comprehensible and reviewable, and enable others (e.g. new team members) to get started – for example through a concise architecture overview.
• We want to ensure that the solution does not degrade over time – that principles, patterns, and concepts continue to be followed.
• We sometimes need to provide documentation alongside our software to meet contractual or regulatory requirements.
Even though Generative AI is currently reshaping the IT world, these goals – and the associated tasks – will remain. Nevertheless, AI opens up exciting new possibilities. Let’s take a closer look.
Documentation approaches with AI
Figure 1 illustrates a range of activities around architecture design and documentation where tools can provide support. This was already the case before Generative AI – for example, automation plays a key role in Docs-as-Code. However, technological progress has opened up new possibilities. Let’s briefly look at three concrete and already widely used approaches involving Generative AI.
Figure 1: The world of classical architecture documentation with selected Gen AI approaches
Approach 1: Co-create and capture results through dialogue
At an early stage of architecture design (e.g. the architecture vision), Generative AI can act as an interactive sparring partner. It helps refine quality goals (arc42, section 1.2), structures constraints (section 2), and suggests ideas for architectural approaches in the solution strategy (section 4).
When documenting decisions in ADRs (section 9), AI can apply the team’s preferred template and generate a first draft of the document from bullet points. Other content, such as system context (section 3), can also be iteratively created and refined together with AI through dialogue.
Approach 2: Derive content from the codebase
Generative AI can help extract structured documentation from source code. It generates initial drafts of the building block view (arc42, section 5) based on code structures, comments, dependencies, and build scripts – including modules, responsibilities, and relationships.
Specialized AI agents can derive C4-style diagrams at the component or container level, for example using Mermaid. Others can identify the technology stack, including programming languages and frameworks.
However, traceability remains a limitation: why a team chose a particular technology is often not visible. Source code does not tell the full story.
Approach 3: Review documentation artifacts (internally or against external references)
Generative AI can not only support the creation of documentation but also its systematic review. Suitable agents can check existing documentation for internal consistency. For example, do the described solution strategy and the architectural decisions or concepts contradict each other?
It is also possible to compare documentation against internal guidelines or external standards. In regulated environments, documents can be checked against norms and standards to identify potential issues. Manual review work becomes a verification step that can increasingly be automated with Generative AI.
What Generative AI takes off our hands – and what it doesn’t
In many organizations, the use of Generative AI is now governed by policies. Initially, this was a significant hurdle in many places: “Am I even allowed to use these tools in my work?” For sensitive architectural information, it is still essential to carefully review applicable guidelines.
Regardless of this, the approaches described above present both opportunities and risks. Generative AI lowers the barrier to creating an initial version of documentation. It creates a first draft from bullet points, which the team then revises. Or it effortlessly builds a first diagram in PlantUML, even if the team hasn’t yet mastered the syntax. It can also help less experienced team members critically assess an architecture and identify gaps – for example: are all quality goals reflected in the solution strategy (section 4)?
On the other hand, there are risks. Generative AI may produce plausible-sounding text that is not necessarily correct. Gaps may be filled with imaginative but inaccurate content. Documentation can become useless – and in regulated environments, errors can even have legal consequences. And what about acceptance and ownership within the team for an architecture overview that, in the extreme case, an AI has churned out at the push of a button?
I believe that we will continue to take responsibility for architecture documentation that fulfills the goals outlined above. Generative AI supports us in creating and maintaining it – and will likely provide new ways of accessing knowledge in the future. Being able to “chat” with an architecture description is already possible today. But the actual thinking remains with the team.
