Docs & Code Guide

Documentation in the repo vs the wiki: a rule for splitting the two

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Every engineering team relitigates this. One camp wants documentation next to the code so it versions with the code and gets reviewed in the same pull request. The other camp points out that the people who most need to read and correct the docs, support, product, the new manager, will never open a pull request. Both are right, which is why the argument never ends. The way out is not to pick a winner but to split the content along the line that actually matters: whether a page has a version.

Try it free
7 min readFor teams whose documentation is currently in three places

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

155/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

What each location is actually good at

Documentation in the repository inherits the review workflow for free. A change to docs/runbooks/deploy.md ships in the same pull request as the change to the deploy script, gets read by the reviewer who already has the context loaded, and lands atomically. It also inherits branching: the docs on the release-2.4 tag describe release 2.4, which is the only honest answer when you support more than one version at once.

A wiki inherits the audience. Anyone can fix a typo from a browser, comment on a paragraph, link a ticket, and search across every team without cloning anything. That matters more than engineers usually admit. A correction that requires a local checkout, a branch and a reviewer is a correction that does not get made.

The failure mode of each is predictable. Repo docs are correct and unread. Wiki docs are read and wrong, because nothing in the wiki has any relationship to the commit that invalidated it. Most teams end up with both failures at once because they never decided which content goes where.

The rule: does this page have a version number

Content that describes a specific state of the code belongs in the repository. Config keys, environment variables, module layout, API request shapes, the commands in a runbook, migration steps, local setup. If someone can point at a commit that made the page wrong, the page should have been in that commit.

Content that describes people and intent belongs in the wiki. On-call rotation, escalation paths, the glossary, meeting notes, the roadmap, how to request access, why the team is organised the way it is. None of that has a version, none of it belongs in a diff, and all of it needs to be editable by someone who does not have a git client.

That leaves one genuinely hard category: the architecture overview. It is versioned, because the architecture changes with the code. It is also the single page the widest non-engineering audience reads. Do not resolve this by copying it into both places. Resolve it by keeping one canonical source and referencing it from both.

repo/
  README.md              # what this service is, how to run it, the diagram
  ARCHITECTURE.md        # the codebase map, boundaries, invariants
  docs/
    runbooks/            # commands, so they version with the commands
    adr/                 # decisions, immutable, numbered
    config-reference.md  # generated from the schema, never hand-edited

wiki/
  On-call rotation
  Access requests
  Glossary
  Team charter
  Architecture overview  -> links to the repo, embeds the same diagram

The diagram belongs in both places, but only once

A diagram copied into two systems is two diagrams, and within a quarter they disagree. The fix is to keep one canonical diagram and reference it by URL from every surface that needs it. A live embed is one markdown line in the README and one paste in Confluence or Notion, and both render the current state of the same canvas. Readers need no account, so the wiki audience is served without anyone exporting anything.

That works because the canonical version regenerates on its own. Connect the repository read only through GitHub, GitLab or Azure DevOps, pick a branch or a tag, and repository sync redraws the diagram and rewrites an architecture doc on a daily cycle. The README and the wiki page then age at the same rate as the code rather than at the rate of whoever last remembered.

Two mechanisms make this safe to leave running unattended. Every sync hashes what actually feeds the diagram, the parsed draw plan for a Terraform repository or the assembled file corpus otherwise, into a 32-character structure fingerprint. When that fingerprint is unchanged the sync stops before generation, so a commit that only touched a README, a test or a comment produces no new picture and the wiki page does not flicker for a dependency bump. And a node someone dragged more than twelve pixels from where the last sync left it is treated as hand-placed and pinned, so a regeneration restores it instead of re-laying it out.

Migrating without a big-bang move

Do not schedule a documentation migration. They stall at forty percent and leave you with a third location. Instead, freeze the losing side: stop creating new pages there, and add a one-line pointer at the top of the pages that are already there.

Then move on demand. When someone asks a question that a wiki page half answers, move that page into the repo as part of answering, and replace the wiki page with a link. After a quarter you will have moved everything anyone actually reads, and the rest can rot without consequence because rotting is exactly what unread pages should do.

Keep a dated index of what moved. The most common complaint after a migration is not that content was lost but that nobody can find where it went, and a single index page fixes that for the cost of five minutes a week. See wiki rot for what happens when you skip this step.

One canonical picture, two audiences

Engineers read it in the README, everyone else reads it in the wiki, and both come from the same synced canvas. See how repository sync works.

FAQ

Should engineering documentation live in the repository or in a wiki?

Split it by whether the content has a version. Anything a commit can invalidate, such as config keys, module layout, runbook commands and API shapes, belongs in the repository so it versions and gets reviewed with the code. Anything about people and intent, such as on-call rotations, glossaries and access requests, belongs in the wiki where non-engineers can edit it.

Why do wiki pages go out of date faster than repo docs?

Because nothing connects a wiki page to the commit that made it wrong. Repo documentation changes in the same pull request as the code and is reviewed by someone with the context loaded. A wiki page is edited weeks later, by someone else, if at all.

How do I avoid maintaining the architecture diagram in two places?

Keep one canonical diagram and reference it by URL from every surface. A live embed renders the current canvas inside a README, Confluence or Notion from a single markdown line, so there is no exported copy to drift. Viewers need no account to see it, which is what makes the wiki audience reachable without an export step.

Is a docs folder in the repo enough on its own?

For versioned content, yes. It is not enough for content that support, product and management need to correct, because a fix that requires a branch and a reviewer usually does not get made. Most teams need both locations with a clear rule about which content goes where.

What is the fastest way to migrate documentation out of a wiki?

Do not run a migration project. Freeze new page creation on the wiki, add a pointer at the top of existing pages, then move pages one at a time as questions come in. Everything nobody asks about can be left behind, and a dated index keeps people from losing track of what moved.