Consistent terminology throughout
Why it matters
Inconsistent terminology in documentation signals to readers that the codebase was written in separate sessions without coordination — because it usually was. When 'API key' in the authentication section becomes 'token' in the code examples and 'credential' in the error reference, readers must constantly re-orient to confirm these are the same thing. For vibe-coded projects built across multiple AI sessions, terminology drift is nearly universal: each session invents its own names for the same concepts. iso-25010:2011 analysability is directly degraded by terminology inconsistency — the documentation costs more cognitive effort per reading.
Severity rationale
Medium because terminology inconsistency doesn't prevent use outright, but it compels every reader to do disambiguation work on every reading, multiplying comprehension cost across the entire user base.
Remediation
Audit the docs for each core concept and pick one term, then enforce it everywhere. For projects with multiple similar concepts, maintain a terminology reference at docs/TERMINOLOGY.md or src/docs/glossary.md:
| Concept | Use | Never Use |
|---|---|---|
| Authentication credential | API key | token, secret, credential |
| Primary SDK object | client | instance, sdk, connection |
| HTTP endpoint | endpoint | route, path, URL |
Update all code examples to match the chosen terms — variable names in code that contradict prose terminology are the most common failure mode. Before evaluating, extract and quote every term used for the same concept across three or more documentation sections.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the Developer Documentation Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · maintainability.analysability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from developer-documentation·automated