Put the documentation under its own linter
Put the documentation under its own linter — a per‑file line budget
that only ratchets down, an index requirement and a real‑path check
— which found six of nine plans marked done while carrying unchecked
boxes, and fourteen commit‑gating tasks named in no document.
August 2026

Situation. The repository governs itself with written instructions —
twenty‑six documents covering the quality policy, the design system,
accessibility, print, metadata, translation and git. Instructions
have a specific decay pattern: they get longer, they drift from the
code, they start referring to files that moved, and at some size
they stop being read. An unread rule is not a rule.

Task. The documentation needed the same treatment as the code — a
linter with limits that fail rather than advise.

Action. Eight policies, each mechanical. A hard ceiling on document
length and a softer one that warns. A per‑file line budget that only
ever ratchets downward, so a document can shrink and cannot grow
back. An index requirement above a threshold, and a section index
above a smaller one. A location rule about which document owns which
subject. Link validity. Plan honesty — the status a plan claims must
match its own checkboxes. A rule that every task gating a commit is
named in some document. And a real‑path check, that every
directory‑qualified path and every code symbol a document names
actually exists. The first run was the argument for the whole
exercise: six plans marked done while carrying unchecked boxes,
fourteen tasks gating every commit and named in no document at all,
three broken links, one orphaned document, and three dead paths
across five documents. The budget then refused its own author —
writing the summary of this work into the development document
pushed it past its limit, which is how a separate document came to
exist, which is the policy working exactly as intended.

Result. Twenty‑six documents totalling about 2,666 effective lines,
each under a budget that cannot grow, with every path and symbol
they name checked against the tree. The uncomfortable finding is the
one worth repeating: fourteen checks were gating every single commit
while appearing in no document, so the rules the machine enforced
and the rules the humans read had already come apart.

Categories:
1Automation & CI/CD	/categories/automation/	engineer.company	70
1Testing & QA	/categories/testing/	engineer.company	70
1Python	/categories/python/	engineer.company	70
1Technical Leadership	/categories/technical-leadership/	engineer.company	70
1Project Management	/categories/project-management/	engineer.company	70
1Documentation	/categories/documentation/	engineer.company	70

Services:
1Technical Leadership & Consulting	/services/technical-leadership/	engineer.company	70
1Project Management (Agile)	/services/project-management/	engineer.company	70
1Technical Documentation	/services/technical-documentation/	engineer.company	70

hThis page on the web	URL:https://engineer.company/portfolio/put-the-documentation-under-its-own-linter/	engineer.company	70
