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.
Medium because poor navigation slows every user but does not block any single task.
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.
ID: developer-documentation.maintenance.navigation
Severity: medium
What to look for: If the project has documentation beyond a single README, check whether there is a navigation structure: table of contents in the README, sidebar navigation in a docs site, an index page listing all doc pages, or a clear directory structure. Users should be able to find what they need without guessing file names. Count all instances found and enumerate each.
Pass criteria: Documentation has a discoverable navigation structure. For README-only projects: a table of contents with anchor links if the README exceeds 500 lines. For docs sites: sidebar or top navigation. For docs/ directories: an index.md or clear naming convention.
Fail criteria: Documentation spans multiple files but has no index, table of contents, or navigation. Users must browse the file tree to find relevant pages.
Skip (N/A) when: Documentation is a single README under 500 lines.
Detail on fail: Example: "docs/ directory contains 12 markdown files but no index page, table of contents, or navigation sidebar" or "README is 800 lines with no table of contents -- users must scroll to find sections"
Remediation: Add navigation appropriate to the documentation format:
<!-- For README: add a table of contents -->
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
For docs sites, configure a sidebar with logical groupings (Getting Started, API Reference, Guides, Advanced).