Skip to main content

No placeholder or stub content

ab-001004 · developer-documentation.content-quality.no-placeholders
Severity: highactive

Why it matters

Placeholder text (TODO, TBD, FIXME, Coming soon, unmodified create-next-app boilerplate) tells every evaluator that the project is unfinished and the maintainers are not shipping. It is worse than an absent section because it actively signals neglect. For commercial libraries this kills sales; for open-source projects it suppresses stars, contributions, and external integrations. Boilerplate READMEs also leak through search results and SEO-penalize the project against competitors who wrote real content.

Severity rationale

High because placeholders actively signal project abandonment and erode evaluator trust immediately.

Remediation

Grep the repo for TODO, TBD, FIXME, Coming soon, Lorem ipsum, and [insert across README.md, CONTRIBUTING.md, and docs/**/*.md. For each hit, either write the actual content or delete the section outright — a missing section is better than one flagged as broken. Example fix:

<!-- Before -->
## Configuration
TODO: Add configuration docs

<!-- After -->
## Configuration
Configuration is set via environment variables documented in `.env.example`.

Detection

  • ID: developer-documentation.content-quality.no-placeholders

  • Severity: high

  • What to look for: Search all documentation files (README, docs/, CONTRIBUTING.md, etc.) for placeholder text: TODO, TBD, FIXME, "Coming soon", "Work in progress", "Lorem ipsum", "Add description here", "[insert", "placeholder", or sections that are headers with no content beneath them. Also check for auto-generated boilerplate that was never customized (e.g., create-react-app README, default Next.js README). Count all instances found and enumerate each.

  • Pass criteria: No placeholder text exists in any documentation file. All sections have substantive content. No TODO or TBD markers in user-facing docs. At least 1 implementation must be confirmed.

  • Fail criteria: Any documentation file contains placeholder text, TODO markers, empty sections (header with no content), or unmodified boilerplate. One placeholder is a fail -- documentation should be complete or the section should be removed.

  • Skip (N/A) when: Never -- this check applies to any project with documentation files.

  • Detail on fail: List the placeholders found. Example: "README.md contains 3 TODOs: 'TODO: Add API docs', 'TODO: Add examples', 'TBD: Configuration options'" or "docs/api.md has 4 empty sections -- headers with no content beneath them" or "README is unmodified create-next-app boilerplate"

  • Remediation: Either write the content or remove the placeholder section. Incomplete documentation with TODO markers is worse than no section at all -- it tells users the docs are unreliable:

    <!-- Bad: -->
## Configuration
TODO: Add configuration docs

<!-- Good (if not ready): remove the section entirely -->
<!-- Good (if ready): write actual content -->
## Configuration

Configuration is set via environment variables or a `config.json` file at the project root.

| Variable | Required | Description |
|----------|----------|-------------|
| API_KEY | Yes | Your API key from the dashboard |

Taxons

placeholder-hygiene

History