Codebase Documentation That Stays Current

Good codebase documentation is generated from the source tree and git history, refreshed for the pages each commit touches, and checked against the code so stale claims get flagged. Hand-written pages rot because nothing fails when they go wrong. With repowise you run repowise init once, repowise update after commits, and read the result in the dashboard, as exported files, or through your coding agent.

What belongs in codebase documentation

Codebase documentation answers four different questions, and each wants a different source. The Diátaxis framework names them: tutorials (learning), how-to guides (tasks), technical reference (facts) and explanation (reasons). Most teams write the first two by hand and let the last two decay.

Reference and architecture are facts about the tree, so a machine can produce them and keep them right. Explanation is the knowledge that lives in people's heads, so it needs to be captured where it already appears: commit messages, comments and ADR files. Only the human-written layer needs a person to maintain it, and a drift check (below) covers the checkable part of that too.

Step 1: Generate the wiki from the code

repowise init builds a wiki page for every eligible source file, selected public symbol, subsystem, dependency cycle, infrastructure file and API surface, plus a repository overview and onboarding pages. Most of it is rendered from the parse, the import graph and git history with no model in the loop, so a keyless run produces a complete wiki.

pip install repowise
cd your-repo
repowise init --no-prose    # keyless and free: the whole wiki from structure
repowise serve              # browse it at localhost:3000

A provider key adds prose to the subsystem pages and the top-level narrative (overview, getting started, key concepts). Add it later with repowise generate, which writes only the pages still unwritten. Pick a voice with repowise init --wiki-style (comprehensive, caveman for token-lean agent reading, reference or tutorial) and switch later with repowise restyle.

The repowise wiki for the repowise repository: a docs tree on the left, a repository overview page in the center and related files and symbols on the right

Every page carries a confidence value. Pages rendered from structure score 1.0 because everything on them was extracted, and model-written pages score 0.8 because they summarise. The score tells a reader how far to trust the statements.

Step 2: Refresh only what changed

repowise update re-renders the pages affected by your commits and leaves the rest alone. It finds the files changed since the last sync, walks the dependency graph for the pages those changes touch, and regenerates those, typically a handful per commit. Model-written pages are reused verbatim when the prompt and model are unchanged, so an unchanged page costs no tokens.

repowise update                 # after a commit or pull
repowise generate --stale       # rewrite prose whose code changed since it was written

Pages also carry a freshness status of fresh, stale, expired or unknown, so a reader sees which pages to double-check before relying on them.

Step 3: Check the references your docs make

A drift check settles the claims a document makes about the tree: paths, links, heading anchors, commands and symbol names. repowise doc-drift runs automatically during init and update, needs no model, and reports references the repository refutes.

repowise doc-drift --kind anchor          # links broken by a renamed heading
repowise doc-drift --min-confidence 0.9   # the ones worth fixing blind

A finding shows the line as written, its heading trail and, when the tree says where the reference went, a likely replacement (a renamed file, a similar heading). repowise never rewrites your documents. A clean run does not claim your prose is true, only that every reference it could resolve, resolved. Mark deliberate examples with <!-- repowise-drift-ignore -->.

Step 4: Capture the why as decision records

Decision records preserve the reasoning that never makes it into a wiki page. An architectural decision record captures a single decision and its rationale. repowise finds that reasoning where your team already wrote it: ADR files, # WHY: comments, commit messages and pull request bodies. ADR files and inline markers need no model key; commit, pull request and comment mining do.

Each record links to the files it governs and carries a verbatim quote. Machine-found records start as proposed candidates, and only a person's repowise decision confirm makes one govern.

repowise decision candidates     # what awaits review
repowise decision confirm a1b2c3d4
repowise decision health         # stale decisions, ungoverned hotspots

A repowise decision record for the repowise repository, showing context, decision, a verified quote and the modules and files it governs

Step 5: Give the docs to your agents

The wiki is also what your coding agent reads. repowise exposes it over ten MCP tools, so an agent queries the index instead of loading files into its context window.

Retrieval merges full-text and vector results, so full-text and symbol search work with no embedder and semantic search turns on when one is configured. See the MCP overview for setup. When you want the wiki as plain files, run repowise export --format markdown.

Pitfalls

• Treating generated docs as finished. Review the onboarding pages once and confirm decision candidates, because those are the parts that carry judgment.
• Editing wiki_style by hand. Run repowise restyle <name>; changing the config and running update does not re-render pages.
• Reading a clean drift run as proof. It confirms references resolve, not that prose is correct.
• Expecting a template change to be free. A released renderer change re-renders every page of that type once, by design.

Related guides

• Auto-generate codebase documentation with AI
• Keeping documentation fresh
• Best codebase documentation tools in 2026
• Architectural decision records: capture why
• The repowise wiki