Your Wiki Is Where Knowledge Goes to Get Lost — Move the Docs Into the Repo

Somewhere in your company is a wiki page that says the deploy process involves a Jenkins job that was decommissioned in 2022. Everyone knows it's wrong. Nobody updates it, because the person who'd update it doesn't go to the wiki. They go to the repo.

That gap — between where work actually happens and where documentation lives — is the quiet productivity tax almost every engineering org pays. And a growing number of teams are deciding to stop paying it by doing something almost radical in its simplicity: putting the docs where the code is.

Why the Split Happened in the First Place

Wikis and CMS platforms weren't bad ideas. In the 2000s, they solved a real problem: engineers needed a shared place to write things down, and Confluence or MediaWiki was better than nothing. The trouble is that a wiki is a separate country with its own border crossings.

When documentation lives outside the repository, every doc update requires context-switching, separate permissions, a different review process, and — critically — a different trigger. Code changes get reviewed because the pull request demands it. Doc changes get reviewed when someone remembers.

The result is the drift we've all lived through: docs describing API version two while the codebase ships version five. At PlatformDoc, we think the fix isn't better wiki hygiene. It's collapsing the distance entirely.

What Docs-as-Code Actually Looks Like

The movement has a few common ingredients:

• READMEs as the front door. Every service gets one, and it's expected to be current. If the README lies, that's a bug.
• Architecture Decision Records (ADRs). Short markdown files capturing why a decision was made — not just what was decided. They live in the repo, versioned with everything else.
• Inline documentation in the codebase. Docstrings, comments, and generated references that can't drift because they sit next to the thing they describe.
• Docs in the same PR as the change. This is the keystone. If you change behavior and don't touch the docs, the diff makes that omission visible.

The pattern has a name — docs-as-code — and its core promise is that documentation inherits every good habit engineering already has: versioning, review, CI checks, and blame history.

The Tradeoffs Nobody Puts in the Pitch Deck

It's not all upside. Non-engineers — product managers, support teams, technical writers — often live in the wiki and hate markdown. Moving docs into the repo can accidentally wall off the people who need them most.

Discoverability is another honest concern. A well-curated wiki has search and hierarchy; a pile of markdown files in forty repos does not, at least not by default. Teams that succeed usually pair the migration with a docs site generator (MkDocs, Docusaurus, and friends) that builds a browsable site straight from the repo.

And there's a cultural hurdle: some engineers will resist having "docs" show up in their code review. That resistance fades fast once the team agrees that a stale README is a defect, not a nicety.

A Practical Migration Playbook

If you're ready to make the switch, resist the urge to do it all at once.

Week 1–2: Pick one service. Choose something actively developed with a moderately painful wiki presence. Migrate its README and any runbooks into the repo. Announce the wiki pages as deprecated with a redirect note.

Week 3–4: Wire docs into the workflow. Add a PR template checkbox for documentation. Add a CI lint step for markdown. Small friction, big consistency gains.

Month 2: Introduce ADRs. Start with the next three architectural decisions the team makes. Capture the context, the options, the choice. Don't backfill history — you'll drown.

Month 3: Build the front door. Stand up a generated docs site from the repos so non-engineers have a friendly entry point. Keep the wiki around, but as a read-only archive.

Ongoing: Assign ownership. A CODEOWNERS file that includes the docs directory means doc changes route to the right reviewer automatically. Accountability without a new meeting.

The Payoff

Teams that complete this shift report the same thing in different words: the docs stopped being a place and started being a practice. When documentation changes in the same pull request as the code, "the docs are out of date" stops being a recurring complaint and starts being a bug report.

Your wiki had a good run. But knowledge that lives next to the code — reviewed with the code, versioned with the code — is knowledge that survives.