Skip to content
boringdocs

Drift Detection

How boringdocs catches documentation decay before it reaches your users.

What Is Drift?

Documentation drift is the gap between what your code does and what your docs say it does. It happens every time someone ships a feature without updating the docs, renames a function, changes a response format, or adds a parameter.

How Drift Detection Works

boringdocs maintains a baseline — a snapshot of the last known-good state of doc-code alignment. On every run:

  1. The current codebase and docs are parsed
  2. A new mapping is built
  3. The new mapping is compared to the baseline
  4. Differences are reported as drift

Drift Types

Code changed, docs didn't
The most common drift type. A function signature changed, an endpoint was added, or a response schema was updated — but the docs still reflect the old state.
Docs changed, code didn't
Someone updated the docs to describe planned changes that haven't been implemented yet. Or the docs describe behavior that was removed.
Orphaned docs
Documentation exists for code that no longer exists. Dead documentation is worse than no documentation.
Orphaned code
Code exists without any documentation. Users have to guess what it does.

Baseline Management

The baseline is stored in .boringdocs/baseline.json. You can:

  • Accept — update the baseline to match the current state (after reviewing changes)
  • Reject — keep the old baseline and fix the drift
  • Diff — see exactly what changed between baseline and current

Drift Report

$ boringdocs diff

Drift detected since last baseline (2026-05-15):

CHANGED:
  src/api/users.ts — POST /users
    - response schema: added field "preferences"
    - docs not updated

ADDED:
  src/api/orders.ts — GET /orders/export
    - no documentation found

REMOVED:
  docs/api/legacy.md
    - still referenced in navigation

Run `boringdocs baseline --update` to accept these changes.

Thresholds

Configure how much drift is acceptable before the check fails:

drift:
  threshold: warning  # error | warning | info
  max_orphaned_docs: 5
  max_orphaned_code: 0