What if your docs wrote themselves?

Self-writing documentation sounds like a contradiction. Documentation is supposed to be a human activity: an engineer understands something, sits down, and explains it in prose. The idea that documentation could write itself suggests either that the quality would be terrible (AI-generated slop) or that it would be too superficial to be useful (auto-generated READMEs that nobody reads).

Neither is what self-writing docs actually means in practice.

How it actually works

The premise is that the knowledge needed for good engineering documentation already exists. It exists in PR descriptions where engineers explain what they changed and why. In Slack conversations where teams debate architecture decisions, discuss trade-offs, and resolve design questions. In meeting recordings where priorities are set, migrations are planned, and incidents are reviewed. In commit messages, design documents, and code review comments.

This knowledge is currently ephemeral. The Slack thread scrolls off the screen within days. The PR is merged and forgotten. The meeting recording sits in a folder nobody revisits. The knowledge was created, shared, and lost, all within the span of a normal working week.

Self-writing documentation captures this knowledge as it's created and structures it into a persistent, searchable wiki that stays current as the underlying activity changes.

The process works like this:

Connect your sources. GitHub repos, Slack channels, meeting recordings, Discord servers. These are the places where engineering knowledge is already being shared.

The system reads and synthesises. As new PRs are merged, new conversations happen, and new meetings are recorded, the system processes the content, extracts the engineering-relevant knowledge, and integrates it into structured documentation.

The wiki maintains itself. When a PR changes how a system works, the documentation about that system updates. When a Slack conversation resolves a design question, the relevant docs incorporate the decision. The documentation stays current because it's derived from the same activity that changes the underlying systems.

Engineers review and refine. The system produces the first draft. Engineers review, correct inaccuracies, add context, and enrich the documentation with insights that the automated system couldn't infer. The engineer's role shifts from author to editor, which is a ten-minute task rather than a two-hour writing session.

What the output looks like

The generated documentation is structured, cited, and editable.

Structured means it follows consistent formatting: system overviews, API documentation, decision records, change histories, team-specific wikis. The format is standardised, which means the documentation is navigable and predictable regardless of which system it describes.

Cited means every claim in the documentation links back to its source: the PR, the Slack message, the meeting timestamp. An engineer reading the docs can click through to the original context to verify any claim or get additional detail. This is what separates self-writing docs from AI-generated text: the documentation is grounded in real activity, not generated from a model's training data.

Editable means the generated docs are a starting point, not a final product. Engineers can modify, restructure, and annotate the docs. The system learns from these edits, improving future generation.

What it's not

Self-writing docs are not AI-generated text that's been prompted to "write documentation for our codebase." That approach produces generic, often inaccurate prose that reads like a language model guessing at what your system might do.

Self-writing docs are generated from your actual engineering activity: real PRs, real conversations, real meetings. The output describes what actually happened rather than what a model thinks might have happened. The citations provide verifiability. The continuous updating provides currency. The human review provides quality assurance.

The distinction matters because trust in documentation is fragile. Engineers who discover that auto-generated docs are inaccurate will stop reading them just as quickly as they stop reading manually written docs that have gone stale. Self-writing docs earn trust by being verifiable (every claim has a source) and current (the docs update as the system changes).

The sources

Self-writing docs can draw from multiple source types, and the coverage improves as more sources are connected:

GitHub: PR descriptions, commit messages, code review comments, issue discussions. These capture what changed and why.

Slack: Design discussions, architecture debates, incident response threads, decision conversations. These capture the reasoning that doesn't make it into code.

Meetings: Sprint planning, architecture reviews, incident post-mortems, onboarding sessions. These capture the verbal context that's typically lost.

Engineering channels: Dedicated engineering Slack channels, Discord servers, or other communication tools where technical discussions happen.

The more sources connected, the more comprehensive the documentation, and the less likely that critical knowledge falls through the gaps between tools.

Frequently asked questions

How accurate are the generated docs? Accuracy varies by source quality. PR descriptions with clear explanations produce better docs than one-line commit messages. Detailed Slack discussions produce better docs than brief exchanges. The citation system lets engineers verify any claim by checking the original source, and the review step catches inaccuracies before they become trusted.

How much engineering time does setup require? Connecting sources typically takes less than an hour. The system begins generating documentation as soon as sources are connected. The ongoing review time is roughly ten to fifteen minutes per week per engineer, compared to the five hours per week that manual documentation typically consumes.

Can we control what the system captures? Yes. You choose which repos, which Slack channels, and which meeting categories the system reads from. Private channels, sensitive repositories, and confidential meetings can be excluded.

Does this replace Confluence/Notion/our existing wiki? It can replace them or complement them. The self-writing docs system produces structured, searchable documentation that serves the same purpose as a manual wiki, with the advantage that it stays current automatically. Existing wiki content can be preserved alongside the generated docs.

Related reading: Why engineering docs matter, The documentation paradox, Why engineers hate writing docs, Docs that write themselves vs Confluence. Related pages: Self-writing docs, For engineering teams.