A missing or skeletal README is the single most common reason developers abandon a project within the first five minutes. Without a clear statement of what the project does and who it is for, every potential contributor, integrator, or evaluator must read source code to answer the most basic questions. iso-25010:2011 analysability directly penalizes this: a project that cannot be understood without reading its implementation is expensive to maintain and impossible to evaluate. Vibe-coded projects routinely ship with boilerplate placeholders — 'TODO: Add description' or 'This project was bootstrapped with create-next-app' — that communicate nothing.
Critical because a project with no meaningful README cannot be evaluated, adopted, or safely integrated by any external developer, making the entire codebase effectively undiscoverable regardless of its technical quality.
Replace the placeholder or missing README with one that answers three questions in the first 200 words: what does this project do, who is it for, and what problem does it solve. A minimal structure that passes:
# Project Name
One sentence: what this does and why it exists.
## Features
- Feature 1: brief explanation
- Feature 2: brief explanation
## Quick Start
npm install your-package-name
The description must appear in the first two paragraphs, use plain language, and not simply repeat the project name.
ID: developer-documentation.getting-started.readme-exists
Severity: critical
What to look for: Check for README.md (or README.rst, README.txt) at the project root. Verify it is more than 500 characters and contains a clear description of what the project does and who it is for. This is different from code-maintainability's README check -- that audit checks for existence; this audit evaluates whether the README actually helps an external developer understand the project's purpose and decide whether to use it. Count every section heading in the README and enumerate which standard sections are present (introduction, installation, usage, API, contributing, license).
Pass criteria: README exists, is >500 characters, and contains a project description that answers "what does this do?" and "why would I use it?" within the first two paragraphs. The description uses plain language, not just the project name repeated. At least 1 implementation must be confirmed.
Fail criteria: README does not exist, is under 500 characters, or contains only a project title without a meaningful description. Common vibe-coded patterns: "# My Project\n\nTODO: Add description", auto-generated boilerplate from create-react-app or similar, or a README that only says "This project was bootstrapped with [tool]."
Skip (N/A) when: Never -- every project needs a README.
Cross-reference: The install-instructions check validates that the README found here contains actionable setup steps.
Detail on fail: Describe what is missing. Example: "README.md is 47 characters: '# my-app\n\nGenerated by create-next-app' -- no project description, purpose, or usage information" or "No README.md found at project root"
Remediation: Write a README that answers three questions in the first 200 words: (1) What does this project do? (2) Who is it for? (3) What problem does it solve? Start with a one-sentence summary, then expand:
# Project Name
Short description of what this does and why it exists (1-2 sentences).
## Features
- Feature 1: Brief explanation
- Feature 2: Brief explanation
## Quick Start
[Installation and first-use instructions go here]