csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📦 deps(thirdparty): update snapshots

Browse Source
This commit is contained in:
ci[bot]
2026-07-01 16:02:41 +00:00
parent 8301f01888
commit c824ba9d7b
2449 changed files with 555104 additions and 9259 deletions
Download Patch File Download Diff File Expand all files Collapse all files
antigravity-awesome-skills/skills/docs-as-marketing/README.md
+37
View File
@@ -0,0 +1,37 @@
# docs-as-marketing
Transform documentation into a powerful marketing channel that attracts, converts, and retains developers.
## What This Skill Covers
- **Information Architecture**: Structuring docs for discoverability and conversion
- **Quickstart Optimization**: Getting developers to success in under 5 minutes
- **API Reference Best Practices**: Copy-paste code that actually works
- **Search Optimization**: Making docs rank for developer queries
- **Measuring Effectiveness**: Metrics that matter for docs-led growth
## When to Use This Skill
- Planning or restructuring developer documentation
- Optimizing quickstart flows for better conversion
- Improving API reference usability
- Building docs as a developer acquisition channel
- Reducing support tickets through better self-service
## Key Principle
Great documentation is invisible marketing. It reduces friction, builds trust, and turns visitors into advocates—all while helping developers succeed.
## Quick Wins
1. Ensure your quickstart delivers success in under 5 minutes
2. Add copy-paste code examples to every API endpoint
3. Include "What's Next" links on every page
4. Test that all code examples actually run
5. Add "Was this helpful?" feedback to measure quality
## Related Skills
- `api-onboarding` - Reducing time-to-first-API-call
- `sdk-dx` - SDK design that simplifies documentation
- `developer-sandbox` - Interactive playground environments
antigravity-awesome-skills/skills/docs-as-marketing/SKILL.md
+398
View File
@@ -0,0 +1,398 @@
---
name: docs-as-marketing
description: 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...
risk: unknown
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/docs-as-marketing
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---
# Documentation as Marketing
## When to Use
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.
## Overview
Developer documentation serves multiple marketing functions:
- **Acquisition**: Docs rank in search and attract developers actively seeking solutions
- **Activation**: Well-structured quickstarts reduce time-to-value
- **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:
1. **What** is this? (1 sentence)
2. **Why** would I use it? (1-2 sentences)
3. **How** do I use it? (the bulk of the page)
4. **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
```markdown
# 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:**
```markdown
# 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`:
```javascript
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:
```bash
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
1. **One-sentence description** of what it does
2. **Authentication requirements** clearly stated
3. **Request format** with all parameters documented
4. **Response format** with example
5. **Error responses** with common causes
6. **Copy-paste example** that actually works
### Copy-Paste Code That Works
**Critical**: Example code must work when copied. Test it.
**Good Example:**
```markdown
## 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"
}'
```
### Response
```json
{
"id": "usr_123abc",
"email": "developer@example.com",
"name": "Jane Developer",
"created_at": "2024-01-15T10:30:00Z"
}
```
### Errors
| Code | Meaning |
|------|---------|
| 400 | Invalid email format |
| 409 | Email already exists |
| 401 | Invalid or missing API key |
```
**Bad Example:**
```markdown
## POST /users
Parameters:
- email (string)
- name (string)
- org_id (string, optional)
- role (enum, optional)
- metadata (object, optional)
- ...
Returns a user object.
```
### Language-Specific Examples
Provide examples in languages your developers actually use:
- cURL (universal, always include)
- JavaScript/Node.js
- Python
- Go
- Ruby
- PHP
- Your most-used SDK languages
## Search Optimization for Docs
### Docs That Rank
Developer documentation can capture high-intent search traffic.
**Target Query Types:**
1. **Problem queries**: "how to send sms from node.js"
2. **Comparison queries**: "[your product] vs [competitor]"
3. **Integration queries**: "integrate [your product] with [popular tool]"
4. **Error queries**: "[specific error message]"
### SEO Fundamentals for Docs
**Page Titles:**
```
Good: "Send SMS with Node.js | Twilio Docs"
Bad: "Documentation - Messaging - SMS - Send"
```
**Meta Descriptions:**
```
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."
```
**URL Structure:**
```
Good: /docs/sms/send-messages/nodejs
Bad: /docs/section/3/page/27?lang=nodejs
```
### Internal Linking
Create a documentation web, not documentation silos:
- Link related concepts
- Link from reference to tutorials
- Link from tutorials to reference
- Cross-link between SDK docs
## Measuring Documentation Effectiveness
### Key Metrics
| Metric | What It Tells You |
|--------|------------------|
| Time on quickstart | Engagement (but also confusion) |
| Quickstart completion rate | Conversion effectiveness |
| Search → signup rate | Docs as acquisition channel |
| Support ticket deflection | Docs comprehensiveness |
| Page ratings/feedback | Content quality |
| Internal search queries | Content gaps |
### Feedback Loops
**Implement:**
- "Was this helpful?" on every page
- Internal search analytics (what are people searching for?)
- Support ticket analysis (what questions do docs fail to answer?)
- Developer interviews (what's confusing? What's missing?)
## Common Documentation Anti-Patterns
### The "Wall of Text"
**Problem**: Pages with no code, no structure, no visual breaks
**Fix**: Lead with code, use headers liberally, break up paragraphs
### The "Assumed Knowledge" Trap
**Problem**: Assuming developers know your terminology
**Fix**: Define terms on first use, link to glossary
### The "Everything Page"
**Problem**: One page trying to cover all use cases
**Fix**: Separate pages for distinct tasks, link between them
### The "Outdated Quickstart"
**Problem**: Quickstart code that no longer works
**Fix**: Automated testing of documentation code samples
### The "Hidden Prerequisites"
**Problem**: Discovering requirements mid-tutorial
**Fix**: All prerequisites at the top, with version numbers
## Tools
### Documentation Platforms
- **GitBook**: Good for smaller teams, nice defaults
- **ReadMe**: Interactive API docs, metrics built-in
- **Mintlify**: Modern, fast, good DX
- **Docusaurus**: Flexible, self-hosted, React-based
- **Notion**: Quick to set up, limited customization
### Code Sample Testing
- **Doctest**: Python code in docs
- **mdx-js**: JSX in markdown
- **Custom CI**: Run code samples as tests
### Search and Analytics
- **Algolia DocSearch**: Free for open source, powerful
- **Google Analytics**: Basic traffic metrics
- **FullStory/Hotjar**: Session recording, heatmaps
- **Internal search analytics**: What are devs searching for?
## Related Skills
- **api-onboarding**: Optimize the complete first API call experience
- **sdk-dx**: Create SDKs that make your docs simpler
- **developer-sandbox**: Interactive environments that complement docs
- **technical-content-strategy**: Broader content strategy including docs
- **developer-audience-context**: Understanding who you're writing for
## Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.