What a documentation drift check cannot see
PaperDrift catches statements that contradict the code. It does not catch documentation that is accurate and still useless. The honest boundary.
It is worth being precise about what this class of tool does, because the gap is where expectations break.
What it catches
Claims in the documentation that the source contradicts: identifiers, commands, defaults, flags, endpoints that have moved or gone. These are checkable against the code, so they are checked against the code.
What it cannot catch
- Documentation that is correct and unclear. A guide can match the source exactly and still fail to explain anything.
- Missing documentation. A check compares what is written against what exists. It cannot report a section that was never written.
- Stale intent. The code may have changed for a reason the docs never captured, and the docs may describe a behaviour that is still correct but no longer recommended.
- Examples that run but teach the wrong pattern.
Why the boundary matters
A tool that claimed to verify documentation quality would be claiming something it cannot deliver, and teams would find that out at the worst moment. Stating the limit up front means the check gets trusted for the things it genuinely knows.