How I Use AI for Technical Documentation: Practical Experience

AlexeyShamin

I decided to share a bit of my experience. I hope you’ll find it interesting and useful.

How I Use AI for Technical Documentation: Practical Experience

Documentation is always a challenge. It’s rarely complete, hard to keep up to date, and any change in the system can trigger dozens of edits that no one makes. As a result, documentation quickly becomes outdated and stops being useful.

There’s another problem: a single fact can imply multiple others, requiring updates across several documents. If you don’t do that, contradictions appear. For example, you learn something new from an email or chat, but it remains there and never makes it into the documentation.

I want to share practical experience using an AI assistant to maintain documentation for the architecture of a corporate Microsoft Dynamics NAV system, which includes many integrations, servers, and databases.

Key Idea

The agent should not just store text but actively work with information. It:

• Analyzes messages, data, and source code to extract facts
• Maintains a consistent style and structure
• Automatically updates related documents
• Answers questions about the system

I have Visual Studio and GitHub Copilot with Claude Sonnet 4.5. I decided to use this combo to test my documentation idea.

How It’s Set Up

I created a prompt for the agent that performs the main work. The workflow is built around three steps:

1. Extracting information
2. Structuring and storing it
3. Answering questions

I based the storage structure on the principle “one file — one object”:

• An object is a server, service, or system
• Easier for the agent to update and for me to find what I need

But information can overlap. For example:

• Server file lists services
• Services have their own files
• If you change a service, both must be updated
  The agent solves this by synchronizing facts.

To help the agent understand the organization, I created a structure file with:

• Naming rules for folders and files
• Sections and format
  This helps the agent know which facts are important.

Example of Structure File

Principle “One file — one object”

• Each file corresponds to one system/service or one database
• Server files are stored in Servers/
• Only one task file in the root

Hierarchical Organization

• Complex systems in separate folders
• Each system folder contains structured documentation

File and Directory Structure

├── Servers/           # Folder with server descriptions
│ ├── SQL Servers/     # SQL servers
│ │ ├── [Server]-SQL-Overview.md          # General description of SQL service
│ │ ├── [Server]-Databases-Overview.md    # General description of databases
│ ├── File Storage/    # File storages
│ │ ├── [Server]-File-Storage.md          # File storage on specific server
│ │ ├── DFS-File-Storage.md               # Company-wide DFS storage
│ ├── [Server]-Server-Architecture.md     # Server architecture

Examples in Servers/SQL Servers

• ALPHA-SQL-Overview.md — SQL service on ALPHA
• ALPHA-Databases-Overview.md — Databases on ALPHA
• BETA-SQL-Overview.md — SQL service on BETA
• SIGMA-SQL-Overview.md — SQL service on SIGMA

Examples in Servers/File Storage

• BETA-File-Storage.md — File storage on BETA
• DFS-File-Storage.md — DFS paths for company

Contents of [SERVER]-SQL-Overview.md

• SQL Server version
• SQL Server service settings
• SQL Server Agent settings
• Linked Servers
• SQL Agent Jobs
• Monitoring (Extended Events, locks)
• Accounts and permissions

Contents of [SERVER]-File-Storage.md

• Folder/file structure as a tree with short descriptions:

├── Folder/        # Root folder accessible to systems/services
│ ├── SubFolder/   # Subfolders
│ │ ├── File.*     # Files

• For each folder:
  • Who uses it
  • File types stored
  • Links to objects using it
• Service jobs for file storage (cleanup, file moves)
• Only facts about files; logic goes in service documentation

Contents of DFS-File-Storage.md

• DFS path structure as a tree
• Physical path for each DFS path
• Link to server storage documentation

Fact Extraction

Teach the agent to extract facts, not assumptions.

Example:

“On Server 1 we run a SQL Agent Job that copies files to Server 2\Arch.”

Agent should infer:

• There is Server 1 and Server 2
• SQL Server and SQL Agent active on Server 1
• Job with at least two steps
• Server 2 has resource \\Arch
• Network connectivity exists

But do not assume \\Arch is an archive.

Sources of Information

• Emails from admins
• Chats with developers
• Config exports
• Source code

Workflow:

• Pass text to agent → extract facts → update docs
• Add table exports → agent parses and extracts
• Analyze source code → agent records logic and facts

Prompt Example

## Operating Principle
Perform steps strictly in order.

**Step 1: Determine input type**
CODE → Analyze code
DATA → Analyze data
INFORMATION → Analyze text

**Step 2: Determine significant facts**
Use MainDoc/Documentation-Structure.md

**Step 3: Extract and classify FACTS**
FACT = confirmed, exact, current, from primary source

Examples:
- Task NRH-1335 released 24.11.2025
- Trigger OnInsert calls FillDistribList
- Field Unit Price type Decimal

**Step 4: Apply analysis**
**Step 5: Save facts**
Follow structure in MainDoc/Documentation-Structure.md

Structuring and Storage

Defined in Step 5, based on structure file.

Answering Questions

Agent answers only from documentation, no internet.

Examples:

• “What is on Server 2?”
• “Which file storages does the system use?”
• “Where are templates for financial reports?”

Results

• Easier to save and store important info
• I stopped manually structuring data — agent does it
• I query the agent instead of reading docs
• Agent finds inconsistencies and hidden facts
• Most time spent discussing system with agent

Conclusion

AI assistant is a powerful tool for automating documentation.
It’s not just about documentation — it’s about creating a knowledge expert.
We should move in this direction.

Notes

Full prompts not published yet (still refining). If the idea resonates, I’ll prepare and share them