# Documentation

> How inspect.software measures documentation — README, docs directory, documentation site, description, topics, and wiki. 8% of the overall health index.


**Documentation** measures whether a newcomer can learn what a project is and
how to use it. Undocumented software externalizes its cost onto every user;
documented software scales its maintainers' knowledge. For a dependency
decision, documentation is also evidence of care — projects that explain
themselves tend to be projects that maintain themselves.

- **Category:** [Engineering Quality](/wiki/engineering-quality) (40% within category)
- **Weight in overall index:** 8%
- **Metric key:** `documentation`

## How the value is computed

A weighted checklist:

| Component | Weight | Evidence |
| --------- | ------ | -------- |
| README | 30 | a README file at the repository root |
| Documentation directory | 25 | a `docs/` (or equivalent) directory |
| Documentation / homepage site | 15 | a documentation or project website linked from the repository |
| Repository description | 10 | the one-line description set on GitHub |
| Topics | 10 | GitHub topics assigned |
| Wiki | 10 | repository wiki enabled |

## The layers, from essential to discoverable

- **README (30)** is the front door; nothing else is read if it is missing.
- **A docs directory (25)** marks documentation that grew past one file —
  usually guides, reference, or architecture notes.
- **A documentation site (15)** signals sustained investment: rendered,
  navigable docs for users rather than repository visitors.
- **Description, topics, and wiki (30 combined)** are discoverability
  metadata: they determine whether the project can be found and classified
  at all — by people, package indexes, and increasingly by AI tooling.

## Reading the result

- Presence is what is measured, not prose quality — the honest limit of
  external inspection (see
  [signals, not warranties](/wiki/signals-not-warranties)).
- Cross-read with [community health](/wiki/community-health): README overlaps
  as the shared foundation, but the two metrics answer different questions —
  *can it be learned* versus *can it be participated in*.

## Improving the value

- Keep a substantive README: purpose, installation, minimal example, links
  onward.
- Move growing documentation into `docs/` and publish it as a site (GitHub
  Pages or any generator) — the two steps together carry 40 points.
- Set the repository description and topics; enable the wiki where it fits
  the project's workflow.

Related: [community health](/wiki/community-health) ·
[Engineering Quality](/wiki/engineering-quality)