Deck: When auditors ask for evidence, the gap between your Confluence page and your GitHub history is the real compliance risk.
What this article solves: Architecture documentation drifts the moment code ships. This post explains how to keep architecture docs tied to the PRs, tickets, and decisions that changed the system, so that when someone asks "what does this service actually do," the answer is traceable, not tribal.
Who this is for: ICs and tech leads who own services, and the ops or compliance stakeholders who need to verify what actually shipped.
The question that gets asked four times
It was 11:14 on a Tuesday when the compliance officer posted in #platform-audit. Her question was direct: "Can someone confirm which services have access to the payments data store, and when that access was last reviewed?"
The engineering lead recognized the question. He had answered a version of it in a Linear ticket six weeks earlier, and before that in a Slack thread during an incident review. The answer existed. It just wasn't anywhere anyone could find it without knowing to look.
He spent forty minutes reconstructing it. He pulled PR #1203, which had added the new read replica access. He found the Linear ticket where the decision was discussed. He wrote it up in a Confluence page, posted the link, and moved on.
Three weeks later, a different auditor asked the same question.
Why architecture docs go stale so fast
Architecture documentation goes stale because it lives in a different place than the work that changes the architecture.
A Confluence page describes the system as it was when someone last had time to write. The code describes the system as it is. Those two things diverge constantly, and nothing in most engineering workflows forces them back together.
The problem is structural. PRs get merged, services get split, access controls get updated. None of that triggers a doc update. The person who made the change is already on the next ticket. The person who owns the Confluence page may not even know the change happened.
According to a 2023 Stack Overflow developer survey, 62% of developers cite outdated or inaccurate documentation as a significant barrier to productivity. The issue is not effort. It is that documentation is not part of the workflow that changes the system.
What traceability actually requires
Traceable architecture documentation means every claim in a doc links back to the artifact that made it true: the PR that changed the service boundary, the Linear ticket that approved the new data access, the Slack thread where the team debated the tradeoff.
Without that chain, a doc is an assertion. With it, a doc is evidence.
For audit and compliance contexts, this distinction is the whole game. A Confluence page that says "Service A does not have write access to the payments store" is a claim. A doc that links to PR #1203, shows the review comments, and timestamps the merge is a record.
Building that chain manually is the part teams skip. It requires someone to stop mid-sprint, find the relevant artifacts, and write prose that connects them. That almost never happens under deadline pressure.
This is where ScopeDocs changes the equation: it watches where decisions actually happen (GitHub, Slack, Linear) and generates docs that stay anchored to the code and context that made them true.
How review workflows can enforce the connection
The most reliable way to keep architecture docs current is to make doc updates part of the review workflow, not a separate task that follows it.
That means treating a PR that changes service behavior as incomplete until the relevant architecture doc reflects the change. It means ADRs that link to the ticket where the decision was made, not just a summary written after the fact. It means runbooks that reference the actual services and access patterns in production, not the ones that existed at last quarter's offsite.
A few practices that hold up in real teams:
Require doc links in PR descriptions for architectural changes. If PR #1847 adds a new service dependency, the description should link to the architecture doc it affects. Reviewers check the doc as part of approval.
Generate ADRs from the ticket where the decision happened. Most architecture decisions get made in a Linear ticket or a Slack thread, not in a formal document. Capturing that context at the source, with a link back to the discussion, produces a more honest record than a retrospective write-up.
Audit the docs, not just the code. During architecture reviews, pull up the doc and the PR history side by side. If they disagree, the PR is the truth. Update the doc, and note what drifted.
In practice
A platform team at a fintech company was preparing for a SOC 2 Type II audit. The auditors needed evidence that data access controls were reviewed and documented for each service touching cardholder data.
The team had the controls. They did not have the trail.
The engineering lead spent two days reconstructing the history: pulling PRs from GitHub, cross-referencing Linear tickets labeled "security-review," and finding the relevant threads in #infra-decisions. He built a doc in Confluence that mapped each service to its access scope, with links to the PRs that established or changed that access.
The auditors accepted it. But the lead noted in the postmortem that the same exercise would take the same two days next quarter, unless the documentation was generated as the work happened, not reconstructed after the audit request arrived.
The artifacts were always there. PR #1203. Ticket SEC-88. The thread from March 4th. The gap was that nothing had assembled them into a living document.
Architecture documentation checklist
- Every architecture doc links to the PR(s) that last changed the system it describes
- ADRs reference the Linear ticket or Slack thread where the decision was made
- PR templates for architectural changes include a required doc-update field
- Architecture review meetings compare the current doc against recent merge history
- Access control docs include timestamps tied to the PR that established each permission
- Runbooks reference current service names and endpoints, verified against production
- Doc owners are assigned per service, not per team, so ownership survives reorgs
The answer was always there
The compliance officer's question had an answer. It was in a PR, a ticket, and a thread. The cost was not the information. It was the time spent finding it, assembling it, and writing it up in a place where it would be found again.
Architecture docs that stay current are not a writing problem. They are a workflow problem. Capture the answer once, link it to its source, and keep it current as the code changes. That is what makes documentation evidence instead of assertion.
ScopeDocs is built to close that gap automatically.