Technical Writer

技术文档撰写者

出色的文档，正是人们持续使用产品与弃用产品之间的区别。

核心原则

为你的受众撰写，而不是为自己。

好的文档：

• 在用户提问前就解答疑问
• 帮助用户快速取得成功
• 减轻支持工作量
• 在团队间传播知识

---

文档类型

1. API 文档

受众： 集成你的 API 的开发者 目标： 让开发者无需支持协助即可完成集成

2. 用户指南

受众： 终端用户 目标： 帮助用户完成任务

3. 教程

受众： 学习者 目标： 通过实践讲授概念

4. 参考文档

受众： 需要查阅具体信息的开发者 目标： 快速查询参数、方法

5. 架构文档

受众： 维护系统的工程师 目标： 理解系统设计决策

---

阶段 1：API 文档

OpenAPI / Swagger 规范

# openapi.yaml
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1
    description: Production server

paths:
  /users:
    get:
      summary: List all users
      description: Returns a paginated list of users
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                  example: [email protected]
                name:
                  type: string
                  example: John Doe
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized

    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              details:
                type: array
                items:
                  type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

API 文档结构

# User API

## Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer YOUR_API_KEY

Get your API key from the [dashboard](https://dashboard.example.com).

## Base URL

https://api.example.com/v1

## Rate Limiting

- 100 requests per minute per API key
- 1000 requests per hour per API key

Rate limit headers:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99 X-RateLimit-Reset: 1640000000

## Errors

Standard HTTP status codes:

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

Error response format:
```json
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "message": "Must be a valid email address"
  }
}

端点

列出用户

GET /users

返回分页的用户列表。

查询参数：

参数	类型	默认值	说明
page	integer	1	页码
limit	integer	20	每页项目数（最多 100 个）
sort	string	created_at	排序字段
order	string	desc	排序顺序（asc/desc）

请求示例：

curl -X GET "https://api.example.com/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例：

{
  "data": [
    {
      "id": "usr_123",
      "email": "[email protected]",
      "name": "John Doe",
      "createdAt": "2024-01-22T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

创建用户

POST /users

创建新用户。

请求正文：

{
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user"
}

参数：

字段	类型	必填	说明
email	string	是	用户邮箱地址
name	string	是	用户全名
role	string	否	用户角色（默认值：user）

请求示例：

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": "John Doe"
  }'

响应示例：

{
  "id": "usr_123",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2024-01-22T10:30:00Z"
}

SDK

JavaScript / TypeScript

npm install @example/api-client

import { ExampleAPI } from '@example/api-client'

const client = new ExampleAPI('YOUR_API_KEY')

// List users
const users = await client.users.list({ page: 1, limit: 20 })

// Create user
const user = await client.users.create({
  email: '[email protected]',
  name: 'John Doe'
})

Python

pip install example-api

from example_api import Client

client = Client('YOUR_API_KEY')

# List users
users = client.users.list(page=1, limit=20)

# Create user
user = client.users.create(
    email='[email protected]',
    name='John Doe'
)

Webhook

通过 Webhook 订阅事件：

{
  "url": "https://yourdomain.com/webhook",
  "events": ["user.created", "user.updated", "user.deleted"]
}

Webhook 负载：

{
  "event": "user.created",
  "timestamp": "2024-01-22T10:30:00Z",
  "data": {
    "id": "usr_123",
    "email": "[email protected]"
  }
}

更新日志

v1.1.0（2024-01-22）

• 为列表端点添加了 sort 和 order 参数
• 改进了错误消息

v1.0.0（2024-01-01）

• 首次发布

---

## Phase 2: User Guides

### Structure

```markdown
# Getting Started Guide

## What You'll Learn

In this guide, you'll learn how to:
- Set up your account
- Create your first project
- Invite team members
- Deploy to production

**Time required:** 15 minutes

## Prerequisites

Before you begin, make sure you have:
- [ ] An account (sign up at example.com)
- [ ] Node.js 18+ installed
- [ ] Basic command line knowledge

## Step 1: Create a Project

1. Log in to your [dashboard](https://dashboard.example.com)
2. Click **New Project**
3. Enter your project name
4. Select a region (choose the one closest to your users)
5. Click **Create**

![Create Project Screenshot](./images/create-project.png)

**Tip:** You can create up to 5 projects on the free plan.

## Step 2: Install the CLI

Open your terminal and run:

```bash
npm install -g @example/cli

验证安装：

example --version

你应该会看到：example CLI v1.0.0

第 3 步：进行身份验证

登录你的账户：

example login

这将打开浏览器。点击 Authorize 继续。

第 4 步：部署应用

进入应用目录：

cd my-app

部署：

example deploy

你的应用将在 https://your-app.example.com 上线

后续步骤

• 配置自定义域名
• 设置环境变量
• 添加团队成员

故障排除

“Command not found: example”

解决方案： 确保 npm 的全局 bin 目录位于 PATH 中。

运行：

npm config get prefix

将 /bin 添加到 PATH 中。

“Authentication failed”

解决方案：

1. 登出：example logout
2. 重新登录：example login
3. 确保使用的是正确的账户

需要帮助？

• 文档
• 社区论坛
• 支持

---

## Phase 3: Tutorials

### Tutorial Structure

```markdown
# Build a Todo App with Example Framework

## What You'll Build

In this tutorial, you'll build a fully functional todo app with:
- ✅ Add, edit, and delete todos
- ✅ Mark todos as complete
- ✅ Filter by status
- ✅ Persist data to database

**Final result:** [Live Demo](https://todo-demo.example.com)

## Prerequisites

- Node.js 18+
- Basic JavaScript knowledge
- 30 minutes

## Step 1: Set Up Project

Create a new project:

```bash
npx create-example-app my-todo-app
cd my-todo-app
npm install

启动开发服务器：

npm run dev

打开 http://localhost:3000。你应该会看到欢迎页面。

第 2 步：创建 Todo 组件

创建 components/Todo.jsx：

export function Todo({ todo, onToggle, onDelete }) {
  return (
    <div className="todo">
      <input type="checkbox" checked={todo.completed} onChange={() => onToggle(todo.id)} />
      <span className={todo.completed ? 'completed' : ''}>{todo.text}</span>
      <button onClick={() => onDelete(todo.id)}>Delete</button>
    </div>
  )
}

这里发生了什么：

• onToggle 将待办事项标记为已完成/未完成
• onDelete 删除待办事项
• CSS 类 completed 为已完成的待办事项设置样式

步骤 3：创建 TodoList 组件

创建 components/TodoList.jsx：

import { useState } from 'react'
import { Todo } from './Todo'

export function TodoList() {
  const [todos, setTodos] = useState([])
  const [newTodo, setNewTodo] = useState('')

  const addTodo = () => {
    if (!newTodo.trim()) return

    setTodos([
      ...todos,
      {
        id: Date.now(),
        text: newTodo,
        completed: false
      }
    ])

    setNewTodo('')
  }

  const toggleTodo = id => {
    setTodos(todos.map(todo => (todo.id === id ? { ...todo, completed: !todo.completed } : todo)))
  }

  const deleteTodo = id => {
    setTodos(todos.filter(todo => todo.id !== id))
  }

  return (
    <div>
      <h1>My Todos</h1>

      <div className="add-todo">
        <input
          value={newTodo}
          onChange={e => setNewTodo(e.target.value)}
          placeholder="What needs to be done?"
          onKeyPress={e => e.key === 'Enter' && addTodo()}
        />
        <button onClick={addTodo}>Add</button>
      </div>

      <div className="todo-list">
        {todos.map(todo => (
          <Todo key={todo.id} todo={todo} onToggle={toggleTodo} onDelete={deleteTodo} />
        ))}
      </div>
    </div>
  )
}

关键概念：

• useState 用于管理待办事项列表
• map 用于渲染每条待办事项
• filter 用于移除已删除的待办事项

步骤 4：添加筛选功能

更新 TodoList.jsx：

const [filter, setFilter] = useState('all') // 'all', 'active', 'completed'

const filteredTodos = todos.filter(todo => {
  if (filter === 'active') return !todo.completed
  if (filter === 'completed') return todo.completed
  return true
})

// In JSX:
<div className="filters">
  <button onClick={() => setFilter('all')}>All</button>
  <button onClick={() => setFilter('active')}>Active</button>
  <button onClick={() => setFilter('completed')}>Completed</button>
</div>

<div className="todo-list">
  {filteredTodos.map(todo => (
    <Todo key={todo.id} todo={todo} onToggle={toggleTodo} onDelete={deleteTodo} />
  ))}
</div>

步骤 5：保存到数据库

安装 Prisma：

npm install @prisma/client
npm install -D prisma
npx prisma init

在 prisma/schema.prisma 中定义架构：

model Todo {
  id        String   @id @default(uuid())
  text      String
  completed Boolean  @default(false)
  createdAt DateTime @default(now())
}

运行迁移：

npx prisma migrate dev --name init

创建 API 路由 app/api/todos/route.ts：

import { prisma } from '@/lib/db'

export async function GET() {
  const todos = await prisma.todo.findMany()
  return Response.json(todos)
}

export async function POST(request: Request) {
  const { text } = await request.json()

  const todo = await prisma.todo.create({
    data: { text }
  })

  return Response.json(todo)
}

更新 TodoList.jsx，使其使用 API：

useEffect(() => {
  fetch('/api/todos')
    .then(res => res.json())
    .then(data => setTodos(data))
}, [])

const addTodo = async () => {
  if (!newTodo.trim()) return

  const response = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: newTodo })
  })

  const todo = await response.json()
  setTodos([...todos, todo])
  setNewTodo('')
}

你学到了什么

• ✅ 组件组合
• ✅ 使用 useState 管理状态
• ✅ 事件处理
• ✅ 条件渲染
• ✅ API 集成
• ✅ 数据库持久化

后续步骤

• 为待办事项添加截止日期
• 实现拖放重新排序
• 添加用户身份验证
• 部署到生产环境

完整代码

在 GitHub 上查看

---

## Phase 4: Reference Documentation

### Component Documentation

```markdown
# Button Component

## Import

```typescript
import { Button } from '@/components/Button'

用法

<Button variant="primary" size="md" onClick={handleClick}>
  Click me
</Button>

属性

属性	类型	默认值	描述
children	ReactNode	必填	按钮内容
variant	'primary' | 'secondary' | 'danger'	'primary'	视觉样式
size	'sm' | 'md' | 'lg'	'md'	按钮尺寸
onClick	() => void	-	点击处理函数
disabled	boolean	false	禁用状态
loading	boolean	false	显示加载动画
type	'button' | 'submit' | 'reset'	'button'	HTML 按钮类型
fullWidth	boolean	false	按钮宽度填满容器

示例

主按钮

<Button variant="primary">Save</Button>

次要按钮

<Button variant="secondary">Cancel</Button>

危险按钮

<Button variant="danger" onClick={handleDelete}>
  Delete
</Button>

加载状态

<Button loading disabled>
  Processing...
</Button>

全宽

<Button fullWidth>Submit</Button>

无障碍访问

• 使用语义化的 <button> 元素
• 支持键盘导航（Enter、Space）
• 加载时包含适当的 ARIA 属性
• 符合 WCAG AA 对比度要求

相关组件

• IconButton
• LinkButton

---

## Documentation Tools

### Docusaurus (Recommended)

```bash
npx create-docusaurus@latest my-docs classic

cd my-docs
npm start

结构：

my-docs/
├── docs/              # Documentation markdown files
│   ├── intro.md
│   ├── api/
│   └── guides/
├── blog/              # Blog posts
├── src/
│   └── pages/         # Custom React pages
├── static/            # Images, assets
├── docusaurus.config.js
└── sidebars.js        # Sidebar navigation

其他工具

• GitBook - 美观、易用
• MkDocs - Python、简单
• Mintlify - AI 驱动、现代
• ReadMe.io - 专注于 API
• Notion - 内部文档

---

编写最佳实践

✅ 应该做

使用主动语态：

✅ "Click the button to save"
❌ "The button should be clicked to save"

言简意赅：

✅ "Returns user data"
❌ "This endpoint will return the data associated with the user"

使用示例：

✅ "Set `timeout` to 5000 (5 seconds)"
❌ "Set the timeout parameter"

拆分冗长内容：

✅ Use headings, lists, code blocks
❌ Long paragraphs of text

包含错误处理：

✅ Show common errors and solutions
❌ Only show happy path

❌ 不应该做

• 不加解释地使用术语
• 假设读者已有相关知识
• 从自己的角度撰写（“我们”“我们的”）
• 跳过错误情况
• 任由文档过时

---

文档检查清单

快速入门

• 安装说明
• 快速入门指南
• Hello World 示例
• 后续步骤

API 文档

• 说明身份验证
• 记录所有端点
• 请求/响应示例
• 列出错误代码
• 说明速率限制
• 记录 SDK

指南

• 涵盖常见用例
• 提供分步教程
• 包含屏幕截图/视频
• 包含故障排除部分

参考

• 记录所有参数
• 指定类型
• 列出默认值
• 提供示例

维护

• 标明版本
• 维护变更日志
• 检查失效链接
• 每季度审查

---

相关资源

技能：

• api-designer - API 文档
• frontend-builder - 组件文档
• ux-designer - 用户指南

工具：

• Docusaurus
• Swagger/OpenAPI
• GitBook
• Mintlify

---

优质文档 = 开发者满意 = 产品成功。 📖