Scrolls
5 min read
On this page

Guides & Tutorials

Reference docs tell you what is possible. Guides tell you how to do it. These are fundamentally different documents serving fundamentally different needs, and confusing them is one of the most common failures in API documentation. A developer who lands on your reference docs when they need a guide will bounce. A developer who lands on a guide when they need a reference will get frustrated. Both must exist, and both must know what they are.

Tutorials vs Guides

The distinction is critical and widely misunderstood.

Tutorial:
  - Learning-oriented
  - "Follow these steps to build X"
  - The reader has never done this before
  - Every step is explicit
  - Success is guaranteed if steps are followed
  - Teaches by doing

Guide:
  - Goal-oriented
  - "Here is how to accomplish Y"
  - The reader knows the basics
  - Steps assume some familiarity
  - May require judgment calls
  - Teaches by explaining

A tutorial for Stripe would be "Process your first payment." A guide would be "Handle subscription billing with metered usage." The tutorial assumes nothing. The guide assumes you can create a charge and want to do something more complex.

The Quickstart

The quickstart is a special case of tutorial. Its job is to get a developer from zero to working in the shortest possible time. It is the single most important document in your API documentation.

Quickstart structure:
  1. Install the SDK (one command)
  2. Get an API key (link to dashboard)
  3. Make your first API call (copy-pasteable code)
  4. See it work (expected output)
  5. What to do next (links to guides)

Total time: under 5 minutes
Total steps: under 10

If your quickstart takes more than 5 minutes, it is not quick. If it requires more than one prerequisite beyond having an account, simplify it. Stripe's quickstart gets you to a working payment in under 3 minutes. That is the bar.

Good quickstart example:

  ## 1. Install the SDK
  pip install acme-sdk

  ## 2. Set your API key
  export ACME_API_KEY=your_key_here

  ## 3. Create your first widget
  from acme import Client
  client = Client()
  widget = client.widgets.create(name="My Widget", color="blue")
  print(widget.id)

  ## 4. Verify it worked
  You should see output like: wgt_abc123def456

Bad quickstart example:

  ## Prerequisites
  - Python 3.8+
  - pip
  - A valid ACME account with billing enabled
  - Docker (for local development)
  - PostgreSQL 14+ (for webhook storage)
  ...

The bad example has already lost the developer before they write a line of code.

Cookbook Patterns

Cookbooks are collections of self-contained recipes for common tasks. Each recipe solves one specific problem. They are not sequential — a developer should be able to jump to any recipe and follow it independently.

Cookbook recipe structure:
  - Title that describes the goal (not the method)
  - One-sentence summary of what this achieves
  - Prerequisites (keep minimal)
  - The code, complete and copy-pasteable
  - Expected output
  - Common variations
  - What can go wrong

Naming Recipes

Name recipes by what the developer wants to accomplish, not by what API calls are involved.

Good recipe titles:
  - Upload a file and get a signed download URL
  - Send a transactional email with a PDF attachment
  - Retry failed webhooks for the last 24 hours
  - Paginate through all customer records

Bad recipe titles:
  - Using the PUT /files endpoint
  - Email API POST request example
  - Webhook retry endpoint
  - GET /customers with pagination

The developer is searching for their problem, not for your endpoint name.

Migration Guides

Migration guides are the most underinvested category of API documentation. When you ship a breaking change, the migration guide is the difference between angry customers and grateful ones.

Migration guide structure:
  1. What changed and why (briefly)
  2. Who is affected
  3. What breaks if you do nothing
  4. Step-by-step migration path
  5. Before and after code examples
  6. Timeline and deprecation schedule
  7. How to test the migration
  8. Where to get help

Before-and-After Examples

The most valuable part of any migration guide. Show the old way and the new way side by side.

Before (v1):
  response = client.charges.create(
      amount=2000,
      currency="usd",
      source="tok_visa"
  )

After (v2):
  payment_intent = client.payment_intents.create(
      amount=2000,
      currency="usd",
      payment_method="pm_card_visa",
      confirm=True
  )

Key differences:
  - charges.create    -> payment_intents.create
  - source parameter  -> payment_method parameter
  - Token IDs (tok_)  -> PaymentMethod IDs (pm_)
  - Implicit confirm  -> Explicit confirm=True

Do not make the developer figure out the mapping themselves. Spell it out.

Writing Good Steps

Whether tutorial or guide, the quality of your steps determines whether people finish.

One Action Per Step

Bad step:
  3. Create a configuration file at ~/.acme/config.yaml, add your
     API key and region, then restart the daemon.

Good steps:
  3. Create the configuration directory:
     mkdir -p ~/.acme

  4. Create the configuration file:
     cat > ~/.acme/config.yaml << 'EOF'
     api_key: your_key_here
     region: us-east-1
     EOF

  5. Restart the daemon:
     sudo systemctl restart acmed

Each step should have exactly one action and one command. The developer should never have to decide which part of a step to do first.

Show Expected Output

After every command that produces output, show what the developer should see. This is how they know they are on the right track.

  5. Verify the service is running:
     curl http://localhost:8080/health

     Expected output:
     {"status": "healthy", "version": "2.1.0"}

     If you see "connection refused," the service did not
     start. Check the logs: journalctl -u acmed -n 50

Handle Failure Paths

Do not just document the happy path. At every step where something can go wrong, tell the developer what failure looks like and what to do about it.

Concept Guides

Some things cannot be explained with steps. Authentication flows, data models, rate limiting strategies, and webhook architectures need conceptual explanation before a developer can use them effectively.

Concept guide structure:
  - What this concept is and why it matters
  - How it works (the mental model)
  - How it relates to other concepts in your API
  - Concrete examples of the concept in action
  - Common misconceptions
  - Links to the relevant reference docs and tutorials

The concept guide for OAuth in your API should explain your specific OAuth implementation, not OAuth in general. Link to the RFC for background. Focus on what is unique to your system.

Common Pitfalls

  • Tutorials that assume knowledge — if step 3 says "configure your webhook endpoint" without showing how, it is not a tutorial. It is a guide pretending to be a tutorial.
  • Guides that are actually reference docs — "Here is every parameter for the search endpoint" is not a guide. It is a reference page. Guides explain how to solve a problem, not how an endpoint works.
  • Quickstarts that are not quick — if your quickstart has a "Prerequisites" section longer than the quickstart itself, rethink it. Move prerequisites into a separate page and link to it.
  • Untested code samples — every code block in every guide should be tested in CI. Code that does not compile or run is worse than no code, because the developer will waste time debugging your docs instead of building their product.
  • One language only — if your API has SDKs in four languages, your guides should have examples in four languages. A Python developer looking at a JavaScript example has to do a mental translation that introduces errors.
  • Missing the "why" — tutorials tell you what to type. Good guides also explain why. "We use idempotency keys here because payment creation is not safely retryable without them" is the kind of sentence that prevents production incidents.
  • No next steps — every tutorial and guide should end with links to what to read or do next. The developer just finished your quickstart; do not leave them stranded.

Key Takeaways

  • Tutorials are learning-oriented (follow these steps). Guides are goal-oriented (understand this concept, solve this problem). Do not conflate them.
  • The quickstart is your most important document. Five minutes from zero to working. No exceptions.
  • Cookbook recipes are named by goal, not by endpoint. One recipe, one problem, one solution.
  • Migration guides need before-and-after code examples, not just changelogs. Show the developer exactly what to change.
  • One action per step, expected output after every command, and failure paths at every point where things can go wrong.
  • Test every code sample in CI. Untested docs are a liability, not an asset.