Documentation Must Follow Remote Truth
Jun 20, 2026
Some of the riskiest work looks like housekeeping.
A README needs cleanup. A migration table needs updating. A status note is out of date. The final diff may only touch documentation, so the task feels safe.
But if the document describes a live system, the documentation is not the authority. It is a claim about the authority.
The Surface Problem
The surface problem was simple: update the migration documentation so it matched the project.
The real problem was that three sources of truth disagreed:
- files on disk
- remote applied state
- documentation claims
That disagreement changed the work. The document could not be reconciled from the document itself. It also could not be reconciled from local filenames alone. The correct source of truth was the remote system that knew what had actually been applied.
The Real Problem
Documentation that describes external state needs an explicit truth-source contract.
Before updating it, ask:
- What does the repository show?
- What does the remote system show?
- What does the current documentation claim?
- Which one is authoritative for this decision?
- What proof will be captured before the document changes?
If the remote system is the authority, the workflow should fail closed when remote proof is missing. It is better to stop with uncertainty than to publish documentation that makes stale local assumptions look settled.
What Was Discovered
The cleanup exposed a familiar kind of confusion.
Some local files were missing from the documentation. Some non-standard files sat in the same folder as canonical migration files, which made them easy for humans to misread as ordinary migration-history entries. One pending numbered change had to be proved against the remote system before the documentation could honestly describe current state.
The safe path was not to tidy the text first. It was to classify the files, prove the remote state, apply only the bounded pending change, and then update the documentation from post-change truth.
That sequence matters. A document that describes yesterday's state in cleaner language is still wrong.
Why It Matters
This pattern is not limited to database migrations.
It applies to deployment docs, billing configuration, access rules, identity-provider setup, feature-flag state, integration status, customer operations, and any other document that describes something living outside the repository.
The smaller the final diff looks, the easier it is to under-govern the work. That is the trap.
A docs-only diff can still be the result of production-boundary work.
The Better Pattern
Use a three-source truth table before reconciling the document.
| Source | Question | Required proof | | --- | --- | --- | | Files on disk | What changes or artifacts exist locally? | file inventory | | Remote system | What is actually applied or active? | authenticated remote readback | | Documentation | What does the current doc claim? | current doc inspection | | Reconciliation | Which source owns truth? | explicit truth-source decision |
Then follow the sequence:
- Name the external truth source.
- Capture current remote-state proof.
- Inventory local files or artifacts.
- Compare documentation claims against both.
- Classify non-standard or helper files separately from canonical records.
- Apply only bounded, proved changes.
- Reconcile docs from post-change truth.
The Reusable Lesson
Documentation cleanup becomes boundary work when the truth it describes lives outside the repository.
The safe pattern is simple: prove remote truth, classify confusing artifacts, apply only the bounded change, then reconcile documentation from post-change truth.
Documentation must follow the authority, not the other way around.
Related Concepts
- Documentation and Knowledge Capture
- Testing and Verification
- Governance and Risk
- Data Quality
- Infrastructure and Deployment
- Artifact Path Changes Are Contract Migrations
- Fresh Artifact Proof for Safe Recovery
