Transform documentation into a powerful marketing channel that attracts, converts, and retains developers. This skill covers creating documentation that ranks in search, converts visitors into users, and accelerates adoption through exceptional information architecture and...
Transform documentation into a powerful marketing channel that attracts, converts, and retains developers. This skill covers creating documentation that ranks in search, converts visitors into users, and accelerates adoption through exceptional information architecture and...
Use this skill when you need transform documentation into a powerful marketing channel that attracts, converts, and retains developers. This skill covers creating documentation that ranks in search, converts visitors into users, and accelerates adoption through exceptional information architecture and...
Documentation is often a developer's first meaningful interaction with your product. Great docs don't just explain—they market. They reduce friction, build trust, and turn curious visitors into active users who recommend your product to others.
Retention: Comprehensive references keep developers building
Referral: Developers share docs they love, not marketing pages
This skill covers the intersection of technical writing and developer marketing—creating documentation that serves both education and conversion goals.
Before You Start
Review the developer-audience-context skill to understand your target developers:
What problems are they searching for solutions to?
What's their technical sophistication level?
What frameworks and languages do they use?
Where do they currently look for answers?
Your documentation strategy should directly address these audience insights.
Information Architecture That Converts
The Four Types of Documentation
Structure your docs around the four types developers need:
Type
Purpose
Marketing Function
Tutorials
Learning-oriented, step-by-step
Builds confidence, shows product value
How-to Guides
Task-oriented, problem-solving
Demonstrates capability breadth
Reference
Information-oriented, accurate
Proves product depth and reliability
Explanation
Understanding-oriented, conceptual
Establishes thought leadership
Navigation That Reduces Bounce
Good Navigation Structure:
Getting Started
├── Quickstart (< 5 min)
├── Installation
└── Core Concepts
Guides
├── Authentication
├── [Most Common Use Case]
├── [Second Most Common Use Case]
└── ...
API Reference
├── Overview
├── Authentication
├── Endpoints (alphabetical or logical grouping)
└── SDKs
Resources
├── Examples
├── Changelog
└── Support
Bad Navigation Structure:
Documentation
├── Chapter 1: Introduction
├── Chapter 2: Getting Started
├── Chapter 3: Advanced Topics
├── Appendix A
└── API (link to separate site)
Information Hierarchy
Every documentation page should follow this hierarchy:
What is this? (1 sentence)
Why would I use it? (1-2 sentences)
How do I use it? (the bulk of the page)
What's next? (clear next steps)
Quickstart Optimization
Your quickstart is your most important conversion page. Optimize ruthlessly.
The 5-Minute Rule
Developers should reach a meaningful success moment within 5 minutes. If your quickstart takes longer, you're losing developers.
Measure and optimize:
Time from page load to first successful API call
Drop-off points in the quickstart flow
Completion rate
Quickstart Structure
# Quickstart
Get your first [meaningful result] in under 5 minutes.
## Prerequisites- [Specific version] of [language/tool]
- [Account/API key] (link to signup)
## Step 1: Install
[Single command, copy-paste ready]
## Step 2: Configure
[Minimal configuration, explain what each part does]
## Step 3: Run
[The payoff—show them it works]
## What You Built
[Explain what just happened and why it matters]
## Next Steps- [Immediate next tutorial]
- [Reference docs for what they just used]
- [Community/support link]
Good vs. Bad Quickstarts
Good Quickstart:
# Send Your First Message
Send an SMS in under 5 minutes.
## Prerequisites- Node.js 16 or higher
- A Twilio account ([sign up free](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/docs-as-marketing/link))
## Install the SDK```bash
npm install twilio
Send a Message
Create send-sms.js:
const twilio = require('twilio');
const client = twilio('YOUR_ACCOUNT_SID', 'YOUR_AUTH_TOKEN');
client.messages.create({
body: 'Hello from my app!',
to: '+15551234567',
from: '+15559876543'
}).then(message =>console.log(`Sent: ${message.sid}`));
Run it:
node send-sms.js
You should see: Sent: SM1234...
What Just Happened
You authenticated with your API credentials and sent an SMS...
**Bad Quickstart:**
```markdown
# Getting Started
Welcome to our platform! Before we begin, let's discuss
the architecture of our messaging system...
[500 words of background]
## Installation
First, ensure you have the correct version of Node.js.
You can check this by running...
[200 words on version checking]
You'll also need to configure your environment variables.
Create a .env file and add the following variables...
[Complex configuration with 10+ variables]
API Reference Best Practices
Every Endpoint Needs
One-sentence description of what it does
Authentication requirements clearly stated
Request format with all parameters documented
Response format with example
Error responses with common causes
Copy-paste example that actually works
Copy-Paste Code That Works
Critical: Example code must work when copied. Test it.
Good Example:
## Create a User
Creates a new user in your organization.
### Request```bash
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "developer@example.com",
"name": "Jane Developer"
}'
Good: "Learn how to send SMS messages using Node.js and the
Twilio API. Includes code examples and troubleshooting tips."
Bad: "This page contains documentation for the SMS sending
functionality of our messaging product."
