# README with install and usage example

- **Pattern:** `ab-002382` (`sdk-package-quality.docs-maintenance.readme-quickstart`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002382
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002382)

## Why it matters

A README without install command, import statement, and a working usage example forces every prospective consumer to read source code or issue trackers before they can evaluate the package. Adoption stalls at the discovery stage: npm page visitors bounce, stars never convert to weekly downloads, and support channels flood with questions the quickstart should answer. For SDKs, this directly undermines user-experience and content-integrity — the two taxons this pattern is tagged under — because the package's public contract is invisible at the moment of evaluation.

## Severity rationale

High because a missing or boilerplate README blocks nearly every downstream adoption decision and multiplies support load.

## Remediation

Rewrite `README.md` so the first screen answers install, import, and first call. Lead with a one-sentence description, then a bash-fenced install command, then a language-fenced usage example that exercises the package's primary entry point with real input and output. Push badges, contributing guidelines, and deep API reference below the quickstart.

```markdown
# your-package

Brief description of what it does.

## Installation

```bash
npm install your-package
```

## Usage

```ts
import { createClient } from 'your-package'

const client = createClient({ apiKey: process.env.API_KEY })
const result = await client.getData()
console.log(result)
```
```

## Detection

- **ID:** `readme-quickstart`
- **Severity:** `high`
- **What to look for:** Enumerate all sections in the README. For each section, examine `README.md` for consumer-facing content. This check evaluates the README from the perspective of someone who just found this package on npm and wants to know how to use it. Look for:
  1. An install command (`npm install your-package` or equivalent)
  2. An import statement showing how to import the package
  3. A working usage example (not just API signatures, but actual code showing input and output)
  4. Whether the README is auto-generated boilerplate (e.g., Create React App default, "# Getting Started" with generic content)
  **Note:** This check is different from code-maintainability's readme-exists check. That check evaluates whether a README exists with basic project info. This check evaluates whether the README serves package consumers — does it show them how to install, import, and use the package?
- **Pass criteria:** README.md exists and contains: (1) an install command, (2) an import/require statement, and (3) at least one usage example showing the package in action. The example should be specific to this package's API, not generic boilerplate — at least 3 sections required: installation, quickstart example, and API overview. Report: "X README sections found, including installation and quickstart."
- **Fail criteria:** README.md is missing, empty, contains only auto-generated boilerplate (e.g., "This project was bootstrapped with..."), or lacks any of: install command, import statement, usage example.
- **Skip (N/A) when:** Never — every published package needs a consumer-facing README.
- **Detail on fail:** Quote the actual README content showing what is missing. Example: `"README.md exists but contains only the create-react-app boilerplate. No install command, no import example, no API usage example. A developer finding this on npm would have no idea how to use it."`
- **Remediation:** Your README is the landing page for your package. It should answer "How do I use this?" in under 30 seconds.

  ```markdown
  # your-package

  Brief description of what it does.

  ## Installation

  ```bash
  npm install your-package
  ```

  ## Usage

  ```ts
  import { createClient } from 'your-package'

  const client = createClient({ apiKey: 'your-key' })
  const result = await client.getData()
  console.log(result)
  ```
  ```

  Put the quickstart at the TOP of the README, before badges, detailed docs, or contributing guidelines.

Taxons: user-experience, content-integrity

HTML version: https://auditbuffet.com/patterns/ab-002382