Code documentation & architecture documentation generation

Documentation is the first thing to rot: it is written late, rarely updated and missing exactly where new team members or auditors need it. LLMs that read a whole repository can draft docstrings, READMEs, API references, architecture overviews and diagrams, and can be wired into CI so that docs are proposed as pull requests whenever code changes. Typical benefit: faster onboarding, less tribal knowledge, and a readable baseline before a legacy migration (CODE-005).

Problem & value

• Today: documentation is hand-written, patchy and out of date. Architecture knowledge sits in a few heads or in stale wiki pages and slide decks. Legacy systems (COBOL, old Java, undocumented SQL) are the worst case. Onboarding and incident response suffer; auditors ask for technical documentation that does not exist.
• AI value: a good first draft in minutes instead of days, consistent style, coverage of every public function, docs updated in the same pull request as the code, and natural-language Q&A on top of the generated wiki.
• Regulatory pull: the EU Cyber Resilience Act requires technical documentation for products with digital elements, and the AI Act requires technical documentation for high-risk AI systems — both are easier to produce and keep current with generated, code-linked documentation [5][6].

Variants

• Inline documentation: docstrings/JSDoc/Javadoc/XML doc comments, generated in the IDE or in CI.
• Repository wiki & onboarding guides: whole-repo overview, module descriptions, "how does login work?".
• API documentation: reference and examples from OpenAPI specs and code; docs sites that are also readable by AI agents (llms.txt, MCP servers exposed by the docs platform).
• Architecture documentation: C4 context/container diagrams, sequence diagrams, dependency maps, ADR drafts from commit history, arc42 chapters [4].
• Legacy reverse documentation: business rules and data flows extracted from COBOL/PL-SQL before migration (CODE-005); also valuable for public-sector systems with lost documentation.

How it works

1. repo + history + specs
2. parse & index (tree-sitter/AST, dependency graph, call graph, embeddings)
3. plan (which docs, which audience, which structure; config file in repo)
4. generate (LLM per module with retrieved context; diagrams as Mermaid/PlantUML text)
5. verify (render diagrams, compile examples, check links, lint style, compare with AST)
6. human review as pull request
7. publish (docs site / wiki) + staleness check on every later code change

• Context building is the core problem: a repository rarely fits one prompt. Tools combine static analysis (symbols, imports, call graphs) with retrieval over code and a hierarchical summary (function → file → module → system).
• Diagrams as code: the model writes Mermaid/PlantUML/Structurizr DSL, which is rendered and version-controlled, so diagrams diff like text.
• Grounding: every statement should link to source files and lines; claims without a code anchor are flagged.
• Human-in-the-loop: generated docs arrive as pull requests; an engineer who knows the system reviews intent and business rules ("why"), because the model can only describe the "what".

Data preparation

Data needed: source repositories, commit and pull-request history, issue tracker, OpenAPI/IaC files and any existing wikis or ADRs. In an SMB they sit in GitHub/GitLab/Azure DevOps, on file shares, in Confluence or SharePoint wikis, sometimes only on developers' machines.

Typical gaps: code outside version control, missing or conflicting old docs, generated or vendored code that pollutes the context, secrets in repos, unclear module boundaries, and tribal knowledge that never reached a ticket.

Preparation steps: - Bring all code under version control and remove secrets (secret scanners such as gitleaks). - Exclude generated, vendored and binary folders from indexing. - Collect and mark existing docs as authoritative or obsolete (PREP-013, PREP-017). - Provide a short glossary and naming conventions (PREP-015) and a documentation template as gold standard (PREP-016). - Check repo access rights before an assistant indexes everything (PREP-023). - Tools: tree-sitter, ctags, repository indexers, embedding stores.

Rough share of effort: low, about 10-20 percent. Most work is setting scope and review rules, not cleaning data. See GUIDE-003 for a quick readiness check.

Implementation paths

Which path for whom

• SMB: B. Documentation tools run in CI on EU-region APIs and can be wired into the existing repository without new infrastructure; an off-the-shelf assistant (A) is fine for a first quick win.
• Enterprise: C. Source code is a trade secret and one internal platform serves several code use cases (Baukasten effect), so self-hosting pays off.
• Developer: C. Local open-weight models with Ollama or similar run well on a workstation and keep code private.
• Public sector: C. Sovereignty and procurement rules favour self-hosted or sovereign EU cloud models.

Path A — Buy (off-the-shelf)

• Repository wikis: DeepWiki by Cognition/Devin (auto-generated architecture diagrams, docs and source links; free for public GitHub repos, private repos via a Devin organisation; steerable via a .devin/wiki.json file) [1].
• Code-coupled docs: Swimm (docs tied to code snippets, flags docs as outdated when the code changes) [2]; Mintlify and similar docs-as-code platforms for public API docs, with AI-assisted writing and an MCP server per docs site [3].
• IDE/platform assistants: GitHub Copilot, Cursor, JetBrains AI Assistant, Sourcegraph Cody-style tools and Claude Code can generate docstrings, READMEs and explanations (CODE-001, CODE-002).
• EU options: Mistral-based assistants (Mistral Le Chat / Codestral via EU provider); JetBrains (Czech company) and Sourcegraph-like on-prem setups for data-residency requirements. Check each vendor's code retention and training policy.
• Choose A when: a small team wants quick wins and the code may leave the company network.

Path B — Build on cloud APIs (recommended for most)

• Models: a strong code/reasoning LLM (Claude, GPT, Gemini, Mistral Large/Codestral) via EU-region endpoints (Azure OpenAI EU, Vertex AI EU, AWS Bedrock Frankfurt, Mistral La Plateforme).
• Pipeline: a CI job (GitHub Actions / GitLab CI) that, on merge, diffs changed modules, regenerates affected docs and opens a pull request; a coding agent with a documentation rule file can do the same (CODE-002). Docs site with Docusaurus, MkDocs, Sphinx or Doxygen as the renderer; Mermaid in markdown.
• Context tooling: tree-sitter for parsing, an embedding model plus a vector index for retrieval, structured outputs for API tables.
• Choose B when: you want custom structure (arc42, company templates) and CI integration.

Path C — Self-host (open source)

• Tools: DeepWiki-Open (open-source DeepWiki clone with local model support) [7]; Doxygen, Sphinx, MkDocs, Docusaurus for rendering; Mermaid, PlantUML or Structurizr for diagrams.
• Models: open-weight code LLMs such as Qwen3-Coder, DeepSeek-Coder/V3-family, Codestral open variants, gpt-oss, Llama-family; served with vLLM or Ollama; embeddings with bge-m3 or Qwen3-Embedding.
• Hardware: HW2 handles docstring generation with ~30B quantised coders; HW3 gives the long context and quality needed for repository-wide architecture summaries.
• Choose C when: source code is a trade secret, defence/critical-infrastructure rules apply, or there is a large legacy estate to document in bulk.

Path D — Custom training

Rarely worthwhile. Fine-tune a small code model on your own approved documentation style only if volume is very high (millions of lines) and prompts plus retrieval cannot reach the house style. Existing reviewed docs and docstring/code pairs are the training data.

State of the art (2026)

• Repository-level understanding is practical: long-context models plus retrieval and static analysis produce usable architecture overviews, and repository wiki products made this a mainstream feature.
• Agentic documentation: coding agents explore the repo with tools (grep, read, run tests) and write docs, then verify examples by executing them; documentation rule files (e.g. AGENTS.md, CLAUDE.md) both consume and produce this kind of content.
• Docs for agents: llms.txt and MCP-served documentation make docs a machine-readable interface for coding assistants, not just for humans [3].
• Limits and failure modes:
• Describes what code does, not why; business intent, rejected alternatives and constraints are missing.
• Hallucinated behaviour, outdated parameters, invented modules or wrong diagrams on large, unusual or heavily dynamic code (reflection, metaprogramming, config-driven flows).
• Silent drift: generated docs go stale as quickly as hand-written ones unless regeneration is automated.

Shared resources & combinations

• Same stack (llm-code + embedding-text + vector-db): CODE-001 IDE assistants, CODE-003 code review, CODE-005 legacy modernisation, CODE-014 bug triage; one repository index serves all of them.
• Natural combinations: CODE-005 (document first, then migrate), CODE-021 (refactoring with up-to-date docs), CODE-003 (reviewer checks docs diff), KNOW-004 (technical documentation assistant), KNOW-011 (knowledge base generation), DOC-014 (parsing documents for RAG).
• Pipeline: the same CI/agent runtime as CODE-002 (workflow-automation, agent-framework).

Effort, cost & KPIs

• Path A: days; per-seat or per-repository subscriptions.
• Path B: 2–6 weeks for a CI pipeline with templates and review rules; cost is mostly input tokens per changed module, usually small compared with engineer time.
• Path C: 1–3 months incl. model serving; one GPU server plus operations.
• KPIs: documentation coverage of public APIs, share of generated docs accepted without edits, doc staleness (days since code changed vs. docs), time-to-first-PR for new developers, support questions to the platform team, audit findings on missing documentation.

People & change

Involve the development lead (process owner) and IT early, then management for budget and policy. Developers are the end-users and should co-define the documentation template. IT security checks what code leaves the network; legal/compliance checks licence and retention terms of the vendor (GUIDE-010, GUIDE-013).

Works council: depends. Documentation generation itself does not monitor staff, but platforms that log prompts, commits or usage per person are objectively suited to monitoring and trigger co-determination under §87(1) no. 6 BetrVG. §90(1) no. 3 requires timely information when AI shapes work processes. Use a short works agreement that excludes performance evaluation from tool logs (GUIDE-004). Public sector: staff council.

Data protection: commits and tickets contain developer names and sometimes customer data; involve the DPO, sign an AVV, and run a DPIA only if personal data is processed at scale (GUIDE-005).

AI literacy: support the team with a short session on review of generated docs (GUIDE-006). Typical concern: "docs will be wrong". Address with human review in pull requests, source links in every statement and a staleness report. Pilot with one repository and one volunteer team (GUIDE-009); keep humans approving every merged doc change.

Risks, regulation & compliance

• EU AI Act: minimal risk (internal developer tooling). AI literacy (Art. 4) applies. If generated text is published to end users as AI-generated content, check transparency duties (Art. 50) [6]. Generated documentation can support, but does not replace, the technical documentation of high-risk AI systems (Annex IV) or the Cyber Resilience Act technical file [5].
• GDPR: code and history may contain personal data (author names/e-mails in commits, test data, hard-coded customer data, secrets). Sending repositories to cloud APIs needs a data-processing agreement, EU region where required, and secret/PII scanning before indexing.
• IP & confidentiality: confirm vendor retention, no-training terms and licence of open-source code being summarised; protect trade secrets with Path C where needed.
• Prompt injection: repository content (comments, README files from dependencies) can contain instructions aimed at AI agents; run documentation agents read-only with minimal permissions.
• Accuracy: never treat generated architecture documents as authoritative for safety- or compliance-critical systems without engineer sign-off.

Getting started

1. Pick one repository, measure baseline (doc coverage, onboarding time) and decide the audience and structure (README + arc42 overview + API reference).
2. Try a repository-wiki tool (e.g. DeepWiki on a public/open-source part, or a Path A product) and have the original authors grade accuracy, especially the "why".
3. Add a CI job or agent that proposes docstring and docs changes as pull requests; require human review.
4. Add automated checks: build docs, render Mermaid, run code examples, link check, staleness warnings.
5. Scan for secrets/PII before indexing, then extend to more repositories and to legacy systems.

Sources

1. Devin Docs — DeepWiki repository wikis — https://docs.devin.ai/work-with-devin/deepwiki
2. Swimm — code-coupled documentation — https://swimm.io
3. Mintlify documentation — https://mintlify.com/docs
4. arc42 architecture documentation template — https://arc42.org
5. Regulation (EU) 2024/2847 (Cyber Resilience Act) — https://eur-lex.europa.eu/eli/reg/2024/2847/oj
6. Regulation (EU) 2024/1689 (AI Act) — https://eur-lex.europa.eu/eli/reg/2024/1689/oj
7. DeepWiki-Open (open-source implementation) — https://github.com/AsyncFuncAI/deepwiki-open
8. Mermaid diagramming — https://mermaid.js.org