Building a Documentation Agent: AI That Writes and Maintains Technical Docs

The Documentation Maintenance Problem

Writing documentation is hard. Keeping it accurate as code evolves is harder. Most projects have documentation that was accurate at some point but has drifted from the actual implementation. A documentation agent solves this by treating docs as a build artifact: every time code changes, the agent detects what documentation is affected, updates it, and ensures the writing style remains consistent.

The Code-to-Docs Pipeline

The agent watches for code changes, determines which documentation pages are affected, and generates updates.

flowchart LR
    INPUT(["User intent"])
    PARSE["Parse plus<br/>classify"]
    PLAN["Plan and tool<br/>selection"]
    AGENT["Agent loop<br/>LLM plus tools"]
    GUARD{"Guardrails<br/>and policy"}
    EXEC["Execute and<br/>verify result"]
    OBS[("Trace and metrics")]
    OUT(["Outcome plus<br/>next action"])
    INPUT --> PARSE --> PLAN --> AGENT --> GUARD
    GUARD -->|Pass| EXEC --> OUT
    GUARD -->|Fail| AGENT
    AGENT --> OBS
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style OBS fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff

import os
import subprocess
from dataclasses import dataclass
from openai import OpenAI

client = OpenAI()

@dataclass
class DocUpdate:
    file_path: str
    section: str
    old_content: str
    new_content: str
    reason: str

class DocumentationAgent:
    def __init__(
        self, code_dir: str, docs_dir: str, model: str = "gpt-4o"
    ):
        self.code_dir = code_dir
        self.docs_dir = docs_dir
        self.model = model
        self.style_guide = self._load_style_guide()

    def _load_style_guide(self) -> str:
        style_path = os.path.join(self.docs_dir, "STYLE_GUIDE.md")
        if os.path.exists(style_path):
            with open(style_path) as f:
                return f.read()
        return """Default style guide:
- Use active voice
- Present tense
- Second person (you, your)
- Code examples for every concept
- No jargon without explanation"""

    def detect_changes(self) -> list[dict]:
        result = subprocess.run(
            ["git", "diff", "--name-only", "HEAD~1", "HEAD"],
            capture_output=True, text=True, cwd=self.code_dir,
        )
        changed_files = result.stdout.strip().split("\n")
        code_changes = []
        for f in changed_files:
            if f.endswith((".py", ".ts", ".js", ".go")):
                diff = subprocess.run(
                    ["git", "diff", "HEAD~1", "HEAD", "--", f],
                    capture_output=True, text=True, cwd=self.code_dir,
                )
                code_changes.append({
                    "file": f, "diff": diff.stdout
                })
        return code_changes

Mapping Code Changes to Documentation

The agent determines which documentation pages need updating based on what code changed.

import json

def map_changes_to_docs(self, code_changes: list[dict]) -> list[dict]:
    doc_files = {}
    for root, _, files in os.walk(self.docs_dir):
        for fname in files:
            if fname.endswith((".md", ".mdx", ".rst")):
                path = os.path.join(root, fname)
                with open(path) as f:
                    doc_files[path] = f.read()

    changes_summary = "\n".join(
        f"- {c['file']}: {c['diff'][:500]}" for c in code_changes
    )

    response = client.chat.completions.create(
        model=self.model,
        messages=[
            {"role": "system", "content": """Given code changes and
existing documentation files, identify which docs need updating.
Return a JSON array where each item has:
- "doc_file": path to the doc that needs updating
- "section": which section is affected
- "reason": why this doc needs updating
- "code_file": which code change triggered this

Only include docs that genuinely need changes. Return [] if no
docs are affected."""},
            {"role": "user", "content": (
                f"Code changes:\n{changes_summary}\n\n"
                f"Documentation files:\n"
                + "\n".join(
                    f"- {path}: {content[:200]}..."
                    for path, content in doc_files.items()
                )
            )},
        ],
        temperature=0,
        response_format={"type": "json_object"},
    )

    raw = json.loads(response.choices[0].message.content)
    return raw if isinstance(raw, list) else raw.get("mappings", [])

Generating Documentation Updates

For each affected documentation page, the agent generates an updated version that reflects the code changes while maintaining the existing writing style.

def generate_update(
    self, mapping: dict, code_changes: list[dict]
) -> DocUpdate | None:
    doc_path = mapping["doc_file"]
    if not os.path.exists(doc_path):
        return None

    with open(doc_path) as f:
        current_doc = f.read()

    relevant_diff = ""
    for change in code_changes:
        if change["file"] == mapping.get("code_file"):
            relevant_diff = change["diff"]
            break

    response = client.chat.completions.create(
        model=self.model,
        messages=[
            {"role": "system", "content": f"""You are a technical writer
updating documentation to reflect code changes.

Style guide:
{self.style_guide}

Rules:
- Only change sections affected by the code change
- Preserve the document structure and formatting
- Update code examples to match the new code
- Add notes about breaking changes if applicable
- Keep the same tone and voice as the existing doc

Return JSON with:
- "section": which section was updated
- "new_content": the complete updated document
- "reason": summary of what changed and why"""},
            {"role": "user", "content": (
                f"Code diff:\n{relevant_diff}\n\n"
                f"Current documentation:\n{current_doc}\n\n"
                f"Section to update: {mapping['section']}"
            )},
        ],
        temperature=0.3,
        response_format={"type": "json_object"},
    )

    data = json.loads(response.choices[0].message.content)
    return DocUpdate(
        file_path=doc_path,
        section=data["section"],
        old_content=current_doc,
        new_content=data["new_content"],
        reason=data["reason"],
    )

Changelog Generation

The agent also produces changelog entries from code diffs, categorizing changes by type.

def generate_changelog(
    self, code_changes: list[dict], version: str
) -> str:
    diffs = "\n---\n".join(
        f"File: {c['file']}\n{c['diff'][:1000]}" for c in code_changes
    )

    response = client.chat.completions.create(
        model=self.model,
        messages=[
            {"role": "system", "content": """Generate a changelog entry
from the code diffs. Categorize changes as:
- Added: new features
- Changed: modifications to existing features
- Fixed: bug fixes
- Deprecated: features marked for removal
- Removed: removed features
- Security: security-related changes

Write from the user's perspective, not the developer's.
Each entry should be one clear sentence."""},
            {"role": "user", "content": (
                f"Version: {version}\n\nDiffs:\n{diffs}"
            )},
        ],
        temperature=0.3,
    )
    return response.choices[0].message.content

Running the Full Pipeline

agent = DocumentationAgent("./", "./docs")
changes = agent.detect_changes()

if not changes:
    print("No code changes detected")
else:
    print(f"Detected changes in {len(changes)} files")

    mappings = agent.map_changes_to_docs(changes)
    print(f"Found {len(mappings)} docs to update")

    for mapping in mappings:
        update = agent.generate_update(mapping, changes)
        if update:
            with open(update.file_path, "w") as f:
                f.write(update.new_content)
            print(f"Updated {update.file_path}: {update.reason}")

    changelog = agent.generate_changelog(changes, "1.2.0")
    with open("./docs/CHANGELOG.md", "a") as f:
        f.write(f"\n\n{changelog}")
    print("Changelog updated")

FAQ

How do I enforce consistent style across documentation written by different people and the AI?

Load a style guide file into the agent's system prompt. The style guide defines voice, tense, terminology preferences, and formatting rules. The agent applies these rules to every update it generates. Run a separate style-checking pass that flags deviations from the guide, whether the content was written by a human or the AI.

Should the agent auto-commit documentation changes?

In most workflows, the agent should create a pull request with its proposed changes rather than committing directly. This gives a human reviewer the chance to verify accuracy, especially for user-facing documentation where incorrect information could confuse customers. Auto-commit is reasonable for internal changelogs and API reference docs that are purely derived from code.

How do I handle documentation for features that are not yet released?

Use branch-aware documentation generation. The agent reads code from the feature branch and generates docs tagged with the branch name. When the branch merges, the agent moves the documentation from draft to published. This prevents documenting unreleased features in production docs while still keeping documentation in sync with development.

---

#Documentation #AIAgents #Python #TechnicalWriting #DeveloperExperience #AgenticAI #LearnAI #AIEngineering