Field note
What can deterministic documentation linting find?
Rules can identify missing labels, circular definitions, absent units, conflicting codes, broken value-set links, placeholder text, and inconsistent review status. They cannot decide whether a definition is true.
Use linting as a checklist
The lint is deterministic and inspectable. It looks for absent dataset context, missing labels and definitions, circular wording, placeholder language, measures without units, missing semantics, conflicting codes, broken links, and review-state gaps.
Keep findings explainable
A finding is a prompt for judgment, not an automatic fix. The same short definition may be acceptable in one bounded context and inadequate in another.
Human review closes the gap
Reader review, confirmation from whoever owns the collection process, and any professional or repository check are what actually validate meaning and suitability. The lint can only tell you that a rule was or was not satisfied. Use the findings to clear the mechanical gaps quickly, then spend the time you saved on the fields no rule can judge.
Worked example from the sample project
Run the review on the sample and the findings are the ones a rule can genuinely see: access_note has no definition and no label, and two fields are still marked needs-review. The lint is deterministic and inspectable, which matters more than the count. It looks for absent dataset context, missing labels and definitions, circular wording, placeholder language, measures without units, missing semantics, codes that appear as both valid and missing, broken value-set links and review-state gaps.
What it cannot do is decide whether a definition is true. A field whose definition reads good means good would pass a length check and fail a reader, and only the reader can find that. The findings are a checklist against which a person exercises judgement, which is why the same short definition can be acceptable in one bounded context and inadequate in another.
What this does not do
- It does not judge whether a definition is correct, complete for your audience, or true.
- It does not classify sensitivity, quality, governance or fitness.
- A zero-finding project is a project with no rule-visible gaps, not a finished one.
Do this in the studio
Treat every finding as a question, and expect the important gaps to be invisible to it.
- Run the deterministic review and read each finding rather than the count.
- Fix what is genuinely missing and record why anything remains open.
- Take the fields the lint cannot judge to a real reader.
Open the studio at the Reader review station