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.
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.
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.
ID: developer-documentation.content-quality.consistent-terminology
Severity: medium
What to look for: Read through the documentation and check whether the same concept is always referred to by the same name. Common inconsistencies: "token" vs "key" vs "credential", "user" vs "account" vs "member", "endpoint" vs "route" vs "path", "project" vs "app" vs "workspace". Check that code examples use the same variable names and function names that the prose describes. Before evaluating, extract and quote any instances where terminology varies for the same concept across different pages. Count all instances found and enumerate each.
Pass criteria: The same concept uses the same term throughout all documentation. If an API key is called an "API key" in the auth section, it is not called a "token" or "secret" elsewhere. Code examples match the terminology in the prose. At least 1 implementation must be confirmed.
Fail criteria: The same concept is referred to by different names in different parts of the documentation, or code examples use different variable names than the prose describes.
Skip (N/A) when: The project has only a single-page README with fewer than 500 words (not enough content for terminology inconsistencies to matter).
Detail on fail: Example: "Authentication section calls it an 'API key' but code examples use variable name 'token' and the error section calls it 'credentials'" or "README calls the main object a 'client' but docs/ refers to it as an 'instance' and examples call it 'sdk'"
Remediation: Pick one term for each concept and use it everywhere. Create a terminology table if the project has multiple similar concepts:
| Concept | Term to Use | Don't Use |
|---|---|---|
| Authentication credential | API key | token, secret, credential |
| Main SDK object | client | instance, sdk, connection |
| API endpoint | endpoint | route, path, URL |
Maintain a terminology reference in src/docs/glossary.md or a docs/TERMINOLOGY.md file at the project root.