Documentation has navigation structure
Why it matters
An 800-line README with no table of contents or a docs/ directory of 12 unindexed markdown files forces users to scroll, grep, or browse the file tree to find anything. Users who cannot navigate the documentation in under 30 seconds either give up or ask the maintainer directly — both outcomes inflate support cost and suppress adoption. Search engines also rank documentation with clear navigation and anchor links higher, compounding the discoverability loss.
Severity rationale
Medium because poor navigation slows every user but does not block any single task.
Remediation
Add a table of contents to any README over 500 lines with anchor links to each top-level section. For multi-file docs under docs/, create docs/index.md or a sidebar config for your docs site. Example TOC:
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
Group docs-site navigation into Getting Started, Guides, Reference, and Advanced.
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.
Taxons
History
- 2026-04-18·v1.0.0·Initial import from developer-documentation·automated