How LLMs Can Transform Your Architecture Documentation

This blog is the second in my series on how software architects can use Large Language Models (LLMs) to become more productive. In the first blog, we explored how to write better prompts. Now, we turn to something more specific: how these AI tools can help create our architecture documentation.

Remember the last time you stared at a blank document, wondering how to start documenting your architecture? You’re not alone. The blank page problem is intimidating, and turning your solution into clear documentation can feel like a heavy task.

LLMs like ChatGPT can make this process far less painful and even enjoyable. Here’s how to use them effectively to create, structure, and refine your architecture documentation.

Creating Document Templates

Instead of using a generic template for your architecture document, LLMs can generate templates based on your specific project needs. The following prompt examples show how you can start working with your LLM to generate architecture document templates.

Start with a basic prompt such as the following:

As a senior Software Architect, propose a template for documenting my microservices e-commerce platform architecture.

Then, add your project context:

Refine this template for an e-commerce platform handling user authentication, product catalogue, order processing, payments, and inventory management.

You can also assign specialized roles if you want your template to include specific sections, as shown in the example below:

As a Data Architect, please include sections that cover the following topics:

This approach gives you a structure specifically tailored to your project’s requirements, not a one-size-fits-all template.

Writing Your First Draft

The introduction sets the tone for your entire document. It’s important to write an introduction that explains your project and provides context while speaking directly to your intended audience. Here’s an example of how to leverage LLMs:

As a seasoned software architect, please help me write the introduction for an architecture document. The goal is to design a microservices architecture for an e-commerce platform that handles user authentication, product catalog, order processing, payments, and inventory management. The introduction should fit on half a page and target developers implementing this solution.

Notice how this prompt specifies the technical scope, length constraint, and target audience. This specificity helps the LLM generate content adapted to our requirements.

Based on the response you get, you can improve it by providing more context for your project. Then you can proceed with the same approach for the other sections of your document as illustrated below:

Write a “Service Communication” section for our e-commerce platform. Cover how our microservices interact securely and reliably.

Then, you can provide more details to have a better result:

You can drill down into the details by asking questions such as:

Include API endpoint examples, Kafka topic schemas, and circuit breaker configuration snippets.

Each improvement adds nuance and specificity, bringing you closer to documentation that helps your team.

The Human Touch

LLMs are great for drafting, but they don’t know your system like you do. You must still check their output carefully.

Make sure the technical details are correct. Add project-specific elements that the model won’t guess. Edit the tone to match your usual way of writing. And confirm that the document covers all critical areas.

The LLM helps you start and move fast, but the final version must reflect your experience and decision-making.

Finally, if you want to improve the quality of your architecture documentation further, there are other techniques worth exploring. You can find more of them in my book, Generative AI for Software Architects: How to Use LLMs to Boost Your Productivity.