Guide 05

Documentation for Developer Tools

A comprehensive guide to creating documentation that converts. Learnings from Stripe, and how to make docs a growth engine.

Part 1: Docs Philosophy

Docs Radiating Circles

Why Docs Matter More Than You Think

Docs are not just support content. They are:

"If a developer can pick software that is also open source, it's just better." — But even without open source, great docs = transparency.

The Radiating Circles of Developer Experience

Product → Docs → Content → Community

The further you go through product adoption and market maturity, the more "outside" you need to go to deliver value.

Docs are the second circle. Get them right before investing heavily in content and community.

Part 2: Docs Fundamentals (From Ex-Stripe Head of Docs)

First Impressions Matter

What developers see first:

Make it inviting. Show you understand developers.

The Docs MVP

Before anything else, nail this:

The first quickstart experience where a developer:

Don't think about other docs until this works.

Align Docs with Developer Stages

After the quickstart, structure around developer journey:

  1. Getting started
  2. Design
  3. Build
  4. Deploy
  5. Manage

This helps developers find what they need based on where they are.

Part 3: Making Docs Convert

The Signup CTA in Docs Header

Stripe added "Create Account" to their docs header.

Results: Significant conversion impact.

Apollo GraphQL: 20% signup increase from adding signup CTA to docs.

Lesson: Docs visitors are often non-users evaluating your product. Give them an easy path to signup.

Escape Hatches

People land on wrong pages. Example: "Stripe checkout" search can land on dev-focused or no-code page.

Solution: Put a link at the top to redirect to the right page.

"Looking for [other thing]? Go here."

Navigation That Works

Key principles:

Part 4: User Research for Docs

The Most Impactful Research

Method: Get a developer to complete a scenario. Ask them to "think out loud" as they normally would.

This uncovers:

The Internal Test

Quick version: Ask your company devs to review a doc.

Questions:

See if takeaways align with the doc's goal.

Look at Search Results

What people search for reveals:

Many search in Google for "X {BRAND}" or "X {BRAND} docs" — treat these like internal searches.

Part 5: Docs for AI/LLM Era

Writing for LLMs

As AI assistants reference docs, structure for machine readability:

Solving AI Engines vs Docs

From Clerk: As AI assistants become common, ensure your docs are:

Part 6: Measuring Docs

Key Metrics

North Star: Time to first [X]

Quality indicator: Customer satisfaction on doc pages

Search Analytics

What to track:

Use this to:

Part 7: Docs Content Types

Docs Content Types

The Quickstart

Purpose: First success in 15-30 minutes

Structure:

  1. What you'll build
  2. Prerequisites
  3. Step-by-step instructions
  4. Working result
  5. What's next

Tips:

Integration Guides

Purpose: Show how you work with their stack

Structure:

  1. What this integration enables
  2. Prerequisites
  3. Setup steps
  4. Configuration
  5. Testing
  6. Troubleshooting

API Reference

Purpose: Complete technical reference

Best practices:

Conceptual Guides

Purpose: Explain the "why" and "how"

When needed:

Part 8: Visual Elements in Docs

Architecture Diagrams

Why they work:

Code Snippets

Best practices:

Screenshots and GIFs

When to use:

Tips:

Part 9: Doc CTAs

Blog Post CTAs in Docs

The V7 approach:

Where to Place CTAs

  1. Header: Signup/trial
  2. End of articles: Related content, deeper features
  3. Contextual: When discussing features that require upgrade
  4. Sidebar: Persistent but non-intrusive

CTA Copy That Works

Do:

Don't:

Part 10: Docs Infrastructure

Search

Must haves:

Navigation

Patterns that work:

Feedback Loops

Resources & Further Reading

Masterclass

Conversion Optimization

AI & Documentation

Tools