docs-as-marketing

将文档作为营销工具

文档往往是开发者与产品进行首次有意义互动的地方。优秀的文档不只是解释产品，还能发挥营销作用。它们能减少阻力、建立信任，并将好奇的访客转化为活跃用户，让他们向他人推荐你的产品。

概述

开发者文档具有多种营销功能：

• 获客：文档在搜索结果中排名靠前，吸引正在积极寻找解决方案的开发者
• 激活：结构良好的快速入门指南可以缩短实现价值所需的时间
• 留存：全面的参考文档让开发者持续构建
• 推荐：开发者会分享自己喜欢的文档，而不是营销页面

本技能探讨技术写作与开发者营销的交集——创建兼顾教育和转化目标的文档。

开始之前

查看 developer-audience-context 技能，了解你的目标开发者：

• 他们正在寻找解决方案来解决什么问题？
• 他们的技术水平如何？
• 他们使用哪些框架和语言？
• 他们目前会去哪里寻找答案？

你的文档策略应直接回应这些受众洞察。

能促进转化的信息架构

四种文档类型

围绕开发者所需的四种文档类型来组织文档：

类型	用途	营销功能
教程	以学习为导向，循序渐进	建立信心，展示产品价值
操作指南	以任务为导向，解决问题	展示产品能力的广度
参考文档	以信息为导向，准确可靠	证明产品的深度和可靠性
说明文档	以理解为导向，讲解概念	确立思想领导力

减少跳出率的导航

良好的导航结构：

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

糟糕的导航结构：

Documentation
├── Chapter 1: Introduction
├── Chapter 2: Getting Started
├── Chapter 3: Advanced Topics
├── Appendix A
└── API (link to separate site)

信息层级

每个文档页面都应遵循以下层级：

1. 这是什么？（1 句话）
2. 我为什么要使用它？（1-2 句话）
3. 我该如何使用它？（页面的主要内容）
4. 接下来做什么？（明确的后续步骤）

快速入门优化

快速入门指南是最重要的转化页面。请全力优化。

5 分钟规则

开发者应在 5 分钟内获得有意义的成功体验。如果快速入门指南耗时更久，你就会失去开发者。

衡量并优化：

• 从页面加载到首次成功调用 API 所需的时间
• 快速入门流程中的流失节点
• 完成率

快速入门结构

# 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]

好的快速入门与糟糕的快速入门

好的快速入门：

# Send Your First Message

Send an SMS in under 5 minutes.

## Prerequisites
- Node.js 16 or higher
- A Twilio account ([sign up free](link))

## Install the SDK
```bash
npm install twilio

发送消息

创建 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}`));

运行：

node send-sms.js

你应该会看到：Sent: SM1234...

刚才发生了什么

你使用 API 凭证进行了身份验证，并发送了一条 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 参考文档最佳实践

每个端点都需要包含

1. 一句话说明其功能
2. 清晰说明身份验证要求
3. 包含所有参数说明的请求格式
4. 附带示例的响应格式
5. 列出常见原因的错误响应
6. 可复制粘贴且确实可运行的示例

确实可运行的可复制粘贴代码

重要提示：复制示例代码后必须可以运行。请先测试。

良好的示例：

## 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": "[email protected]",
    "name": "Jane Developer"
  }'

响应

{
  "id": "usr_123abc",
  "email": "[email protected]",
  "name": "Jane Developer",
  "created_at": "2024-01-15T10:30:00Z"
}

错误

代码	含义
400	邮箱格式无效
409	邮箱已存在
401	API 密钥无效或缺失

**Bad Example:**
```markdown
## POST /users

Parameters:
- email (string)
- name (string)
- org_id (string, optional)
- role (enum, optional)
- metadata (object, optional)
- ...

Returns a user object.

特定语言的示例

请提供开发者实际使用的语言示例：

• cURL（通用，务必包含）
• JavaScript/Node.js
• Python
• Go
• Ruby
• PHP
• 使用最广泛的 SDK 语言

文档的搜索优化

排名靠前的文档

开发者文档可以吸引具有明确意图的搜索流量。

目标查询类型：

1. 问题查询：“如何使用 Node.js 发送短信”
2. 比较查询：“[你的产品] 与 [竞争对手]”
3. 集成查询：“将 [你的产品] 与 [热门工具] 集成”
4. 错误查询：“[具体错误消息]”

文档 SEO 基础

页面标题：

Good: "Send SMS with Node.js | Twilio Docs"
Bad: "Documentation - Messaging - SMS - Send"

元描述：

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 结构：

Good: /docs/sms/send-messages/nodejs
Bad: /docs/section/3/page/27?lang=nodejs

内部链接

构建文档网络，而不是文档孤岛：

• 链接相关概念
• 从参考文档链接到教程
• 从教程链接到参考文档
• 在 SDK 文档之间交叉链接

衡量文档效果

关键指标

指标	说明
快速入门页面停留时间	参与度（但也可能反映困惑）
快速入门完成率	转化效果
搜索 → 注册率	文档作为获客渠道的效果
支持工单拦截率	文档的全面程度
页面评分/反馈	内容质量
内部搜索查询	内容缺口

反馈循环

实施以下措施：

• 在每个页面添加“这是否有帮助？”
• 分析内部搜索数据（大家在搜索什么？）
• 分析支持工单（文档未能解答哪些问题？）
• 采访开发者（哪些内容令人困惑？缺少什么？）

常见的文档反模式

“大段文字墙”

问题：页面没有代码、结构，也没有视觉上的间隔
解决方法：开篇展示代码，充分使用标题，将段落拆分开来

“默认读者已掌握相关知识”的陷阱

问题：假设开发者了解你的术语
解决方法：首次使用时定义术语，并链接到术语表

“包罗万象的页面”

问题：试图在一个页面中涵盖所有使用场景
解决方法：为不同任务分别创建页面，并在页面间建立链接

“过时的快速入门”

问题：快速入门中的代码已无法运行
解决方法：自动测试文档中的代码示例

“隐藏的前置条件”

问题：教程进行到一半才发现所需条件
解决方法：在开头列出所有前置条件和版本号

工具

文档平台

• GitBook：适合较小的团队，默认设置出色
• ReadMe：交互式 API 文档，内置指标
• Mintlify：现代、快速，开发者体验良好
• Docusaurus：灵活、可自托管，基于 React
• Notion：设置快捷，但自定义能力有限

代码示例测试

• Doctest：文档中的 Python 代码
• mdx-js：Markdown 中的 JSX
• 自定义 CI：将代码示例作为测试运行

搜索与分析

• Algolia DocSearch：开源项目可免费使用，功能强大
• Google Analytics：基础流量指标
• FullStory/Hotjar：会话录制、热图
• 内部搜索分析：开发者在搜索什么？

相关技能

• api-onboarding：优化完整的首次 API 调用体验
• sdk-dx：创建让文档更简单的 SDK
• developer-sandbox：与文档互补的交互式环境
• technical-content-strategy：更广泛的内容策略，包括文档
• developer-audience-context：了解你的写作对象