Deck: When the official doc says one thing and the code says another, someone pays the price. Usually the person who trusted the doc.
What this article solves: Traditional wikis create a false sense of documentation coverage. They look complete and they go stale quietly. Source-linked documentation ties every claim to the PR, thread, or ticket that produced it, so readers can verify what they're reading and trust what they act on.
Who this is for: Backend engineers, engineering managers, and team leads who are tired of chasing down the real answer after the wiki gives them the wrong one.
The doc said it was still there
Priya had been staring at the same README section for ten minutes. The /sync endpoint, according to the wiki, accepted a force_refresh flag. The docs were clear. The example was clean. The page had been edited eight months ago, which felt recent enough.
She passed the flag. The API ignored it.
A quick git log later: PR #1203, merged in February, had removed the flag entirely. The PR description explained why. The Slack thread in #backend-api from that week had three engineers debating the tradeoff. The Linear ticket had the final decision. None of it made it back to the wiki.
Priya spent forty minutes on something that should have taken four. The wiki wasn't wrong on purpose. It just hadn't kept up.
Why wikis go stale by design
A wiki is a writing tool. It has no relationship with your codebase, your tickets, or your Slack threads. When a PR merges and changes behavior, the wiki doesn't know. When a decision gets made in a Linear ticket and the code ships, the wiki doesn't know that either.
The people who made the change move on to the next sprint. Updating the wiki is a separate task, it requires context-switching, and it competes with everything else. According to a 2023 Stack Overflow developer survey, documentation is consistently ranked among the most frustrating parts of the job. The frustration isn't laziness. It's that the workflow doesn't connect.
Static wikis reference deprecated commands and services that no longer exist. On-call engineers stop trusting runbooks. New hires hit dead links and architecture diagrams that don't match the codebase. The knowledge doesn't disappear. It migrates into DMs, into people's heads, into the fourth time someone asks the same setup question in #engineering-onboarding.
What source-linked documentation actually means
Source-linked documentation means every claim in a doc traces back to the artifact that produced it: a PR, a Slack thread, a Linear ticket, a code review comment.
This changes two things at once.
First, it changes how docs get created. Instead of asking engineers to stop and write, the documentation is generated from the work they're already doing. The PR that removes force_refresh produces the doc update. The Slack thread that debated the tradeoff becomes the context. The Linear ticket that closed the decision becomes the record.
Second, it changes how docs get trusted. When a reader sees a claim, they can click through to the source. They're not taking the wiki's word for it. They're reading the PR description, the thread, the ticket. The doc becomes a surface, not a silo.
The trust gap between wikis and teams
The business cost of stale documentation isn't usually visible until something breaks. A bad deploy traced back to a runbook that referenced a service that was deprecated in Q3. An onboarding engineer who spent a week building on an assumption the team had discarded in a code review. A PM who quoted a capability in a customer call that the team had quietly removed.
These aren't edge cases. They're the ordinary cost of documentation that lives separately from the work.
Cross-team trust depends on shared truth. When PMs, EMs, and ICs are reading the same doc and that doc is grounded in the actual code and decisions, the coordination tax drops. When the doc is a wiki that nobody is confident is current, every conversation starts with "let me double-check that."
ScopeDocs connects to GitHub, Slack, and Linear and generates docs that are traceable to the source, so the answer Priya needed was already there, attached to PR #1203, and it would have stayed current when the code changed.
In practice
A team ships a new rate-limiting policy. The decision happened across three places: a Linear ticket where the PM scoped the requirement, a GitHub PR where the engineer implemented it and left detailed review comments, and a Slack thread in #platform where two engineers debated the per-user versus per-org model.
With a traditional wiki, someone has to synthesize all three into a doc, remember to do it, and then remember to update it the next time the policy changes. Nobody does this reliably.
With source-linked documentation, the policy doc is generated from those three artifacts. It links to the PR, the ticket, and the thread. When the policy changes in a future PR, the doc updates. A new engineer reading the runbook six months later sees not just what the policy is, but why it was made, who made it, and where to look if they need more context.
The archaeology goes away. The answer is already there.
Checklist: signs your wiki is costing you more than you think
- Engineers regularly find docs that contradict the current codebase
- The same setup or architecture question gets asked in Slack more than twice a month
- Runbooks reference services, flags, or endpoints that no longer exist
- New hires report that onboarding docs don't match what they find in the repo
- Postmortems reference a decision nobody can trace to a source
- ADRs exist but nobody knows if they reflect what was actually built
- Documentation updates are a separate ticket that consistently gets deprioritized
The answer was already there
The problem with traditional wikis isn't that teams don't care about documentation. It's that the wiki has no memory of the work. Every PR that changes behavior, every thread that settles a debate, every ticket that closes a decision: those are the real documentation. They just need to be captured, linked to their source, and kept current when the code moves.
That's the shift. Not more writing. Better capture.
See how ScopeDocs turns your existing GitHub, Slack, and Linear activity into documentation that stays true.