Skip to main content

Quick start guide gets to working code in under 5 steps

ab-000993 · developer-documentation.getting-started.quick-start
Severity: criticalactive

Why it matters

A missing or bloated quick start is the single strongest predictor of project abandonment. Developers evaluating a library spend 60 to 90 seconds deciding whether to integrate; if they cannot reach working output in that window, they bounce to a competitor. This translates directly to adoption loss, lower GitHub stars, lower npm downloads, and fewer inbound contributions. Teams integrating internally waste hours piecing together setup from scattered docs, inflating onboarding cost per engineer.

Severity rationale

Critical because first-impression friction directly kills adoption and there is no workaround for the evaluator.

Remediation

Write a five-step maximum quick start at the top of README.md that covers install, one file of code, and a run command. The code block must include real imports and produce visible output. Example:

npm install your-package
import { createClient } from 'your-package'
const client = createClient({ apiKey: process.env.API_KEY })
console.log(await client.query('hello'))

Detection

  • ID: developer-documentation.getting-started.quick-start

  • Severity: critical

  • What to look for: Look for a "Quick Start", "Getting Started", or "Usage" section in the README or docs. Count the steps from zero (nothing installed) to seeing the project work (output, running server, rendered component). The example code should be copy-pasteable and produce a visible result.

  • Pass criteria: A quick start section exists that takes the reader from installation to a working "hello world" result in 5 or fewer numbered steps. The code example is complete (includes imports), uses the project's actual API, and produces a visible result. At least 1 implementation must be confirmed.

  • Fail criteria: No quick start exists, or the quick start requires more than 5 steps, or the example code is incomplete (missing imports, uses undocumented functions, or references files that don't exist in a fresh install).

  • Skip (N/A) when: Never -- even complex projects need a minimal getting-started path.

  • Detail on fail: Describe the issue. Example: "No quick start or getting started section in README or docs" or "Quick start example imports from './utils' but doesn't explain what that file should contain" or "Getting started requires 12 steps including setting up 3 external services before seeing any output"

  • Remediation: Write a quick start that a developer can follow in under 2 minutes:

    ## Quick Start
    
    1. Install the package:
       ```bash
       npm install your-package
    
    1. Create a file:

      import { createClient } from 'your-package'
      
      const client = createClient({ apiKey: 'your-key' })
      const result = await client.query('hello')
      console.log(result)
      
    2. Run it:

      npx tsx example.ts
      

Taxons

History