docs-style
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDocumentation Style Guide
文档风格指南
Apply these principles when writing or reviewing documentation to ensure clarity, consistency, and accessibility for both human readers and LLMs.
在撰写或审核文档时遵循这些原则，确保文档对人类读者和LLM都清晰、一致且易于理解。
Voice and Tone
语气与措辞
Use Second Person
使用第二人称
Address the reader directly as "you" rather than "the user" or "developers."
markdown
<!-- Good -->
You can configure the API by setting environment variables.
<!-- Avoid -->
The user can configure the API by setting environment variables.
Developers should configure the API by setting environment variables.直接以“你”称呼读者，而非“用户”或“开发者”。
markdown
<!-- 推荐写法 -->
你可以通过设置环境变量来配置API。
<!-- 避免写法 -->
用户可以通过设置环境变量来配置API。
开发者应该通过设置环境变量来配置API。Prefer Active Voice
优先使用主动语态
Write sentences where the subject performs the action. Active voice is clearer and more direct.
markdown
<!-- Good -->
Create a configuration file in the root directory.
The function returns an array of user objects.
<!-- Avoid -->
A configuration file should be created in the root directory.
An array of user objects is returned by the function.撰写主语执行动作的句子。主动语态更清晰、直接。
markdown
<!-- 推荐写法 -->
在根目录创建配置文件。
该函数返回用户对象数组。
<!-- 避免写法 -->
应在根目录创建配置文件。
用户对象数组由该函数返回。Be Concise
保持简洁
Cut unnecessary words. Every word should earn its place.
markdown
<!-- Good -->
Run the install command.
<!-- Avoid -->
In order to proceed, you will need to run the install command.markdown
<!-- Good -->
This endpoint returns user data.
<!-- Avoid -->
This endpoint is used for the purpose of returning user data.Common phrases to simplify:
| Instead of | Use |
|---|---|
| in order to | to |
| for the purpose of | to, for |
| in the event that | if |
| at this point in time | now |
| due to the fact that | because |
| it is necessary to | you must |
| is able to | can |
| make use of | use |
删除冗余词汇，每个词都要有存在的意义。
markdown
<!-- 推荐写法 -->
运行安装命令。
<!-- 避免写法 -->
为了继续操作，你需要运行安装命令。markdown
<!-- 推荐写法 -->
该端点返回用户数据。
<!-- 避免写法 -->
此端点的用途是返回用户数据。常见简化短语对照表：
| 替代前 | 推荐用法 |
|---|---|
| in order to | 要 |
| for the purpose of | 要/为 |
| in the event that | 如果 |
| at this point in time | 现在 |
| due to the fact that | 因为 |
| it is necessary to | 你必须 |
| is able to | 可以 |
| make use of | 使用 |
Document Structure
文档结构
Write Clear, Descriptive Headings
撰写清晰、具有描述性的标题
Headings should tell readers exactly what the section contains. Avoid clever or vague titles.
markdown
<!-- Good -->标题应准确告知读者该部分的内容。避免使用花哨或模糊的标题。
markdown
<!-- 推荐写法 -->Install the CLI
安装CLI
Configure Authentication
配置认证
Handle Rate Limits
处理速率限制
<!-- Avoid -->
<!-- 避免写法 -->
Getting Started (vague)
入门指南（模糊）
The Fun Part (clever)
有趣的部分（花哨）
Misc (uninformative)
其他（无信息量）
undefinedundefinedCreate Self-Contained Pages
创建独立完整的页面
Assume readers may land on any page directly from search. Each page should:
- Explain what the feature/concept is
- State prerequisites clearly
- Provide complete context for the topic
markdown
<!-- Good: Self-contained -->假设读者可能通过搜索直接进入任意页面。每个页面应：
- 解释该功能/概念是什么
- 明确列出前置条件
- 提供该主题的完整上下文
markdown
<!-- 推荐写法：独立完整 -->Webhooks
Webhooks
Webhooks let you receive real-time notifications when events occur in your account.
Webhooks可让你在账户中发生事件时接收实时通知。
Prerequisites
前置条件
- An active API key with webhook permissions
- A publicly accessible HTTPS endpoint
- 具有Webhook权限的有效API密钥
- 可公开访问的HTTPS端点
Create a Webhook
创建Webhook
...
undefined...
undefinedUse Semantic Markup
使用语义化标记
Choose the right format for the content type:
- Headings: Follow proper hierarchy (h1 > h2 > h3, never skip levels)
- Lists: Use for multiple related items
- Tables: Use for structured data with consistent attributes
- Code blocks: Use for any code, commands, or file paths
markdown
<!-- Good: Table for structured data -->
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| api_key | string | Yes | Your API key |
| timeout | integer | No | Request timeout in seconds |
<!-- Good: List for steps or options -->
To authenticate, you can:
- Use an API key in the header
- Use OAuth 2.0
- Use a service account根据内容类型选择合适的格式：
- 标题: 遵循正确的层级结构（h1 > h2 > h3，请勿跳过层级）
- 列表: 用于多个相关项
- 表格: 用于具有一致属性的结构化数据
- 代码块: 用于任何代码、命令或文件路径
markdown
<!-- 推荐写法：用表格展示结构化数据 -->
| 参数 | 类型 | 是否必填 | 描述 |
|-----------|------|----------|-------------|
| api_key | string | 是 | 你的API密钥 |
| timeout | integer | 否 | 请求超时时间（秒） |
<!-- 推荐写法：用列表展示步骤或选项 -->
进行认证时，你可以：
- 在请求头中使用API密钥
- 使用OAuth 2.0
- 使用服务账号Make Content Skimmable
让内容易于快速浏览
Break dense paragraphs into digestible chunks:
- Keep paragraphs to 3-4 sentences maximum
- Use bullet points for lists of items
- Add subheadings to long sections
- Put key information first (inverted pyramid)
markdown
<!-- Good: Skimmable -->将冗长段落拆分为易读的小块：
- 段落最多保留3-4句话
- 用项目符号列出多项内容
- 为较长的部分添加子标题
- 关键信息前置（倒金字塔结构）
markdown
<!-- 推荐写法：易于浏览 -->Error Handling
错误处理
The API returns standard HTTP status codes.
API返回标准HTTP状态码。
Common Errors
常见错误
- 400 Bad Request: Invalid parameters. Check the request body.
- 401 Unauthorized: Invalid or missing API key.
- 429 Too Many Requests: Rate limit exceeded. Wait and retry.
- 400 Bad Request: 参数无效，请检查请求体。
- 401 Unauthorized: API密钥无效或缺失。
- 429 Too Many Requests: 超出速率限制，请稍后重试。
Retry Strategy
重试策略
For 429 errors, use exponential backoff starting at 1 second.
undefined针对429错误，使用指数退避策略，初始等待时间为1秒。
undefinedConsistency
一致性
Use One Term Per Concept
同一概念使用统一术语
Pick a term and use it consistently. Switching terms confuses readers.
markdown
<!-- Good: Consistent terminology -->
Generate an API key in the dashboard. Use your API key in the Authorization header.
<!-- Avoid: Inconsistent terminology -->
Generate an API key in the dashboard. Use your API token in the Authorization header.Document your terminology choices:
| Concept | Use | Don't use |
|---|---|---|
| Authentication credential | API key | API token, secret key, access key |
| Configuration file | config file | settings file, preferences file |
| Command line | CLI | terminal, command prompt, shell |
选定一个术语并保持一致使用。频繁切换术语会让读者困惑。
markdown
<!-- 推荐写法：术语一致 -->
在控制台生成API密钥。在Authorization请求头中使用你的API密钥。
<!-- 避免写法：术语不一致 -->
在控制台生成API密钥。在Authorization请求头中使用你的API令牌。记录你的术语选择：
| 概念 | 推荐用法 | 避免用法 |
|---|---|---|
| 认证凭证 | API密钥 | API令牌、密钥、访问密钥 |
| 配置文件 | config文件 | 设置文件、偏好设置文件 |
| 命令行 | CLI | 终端、命令提示符、Shell |
Apply Consistent Formatting
应用一致的格式
Use the same formatting for similar content types:
- UI elements: Bold (Click Save)
- Code/commands: Backticks ()
npm install - File paths: Backticks ()
/etc/config.yaml - Key terms on first use: Bold or italics
- Placeholders: SCREAMING_CASE or angle brackets (or
YOUR_API_KEY)<api-key>
对同类内容使用相同的格式：
- UI元素: 加粗（点击保存）
- 代码/命令: 反引号包裹（）
npm install - 文件路径: 反引号包裹（）
/etc/config.yaml - 首次出现的关键术语: 加粗或斜体
- 占位符: 大写形式或尖括号包裹（或
YOUR_API_KEY）<api-key>
LLM-Friendly Patterns
LLM友好格式规范
State Prerequisites Explicitly
明确列出前置条件
List what users need before starting. This helps both humans and LLMs understand context.
markdown
undefined列出用户开始操作前需要准备的内容。这有助于人类读者和LLM理解上下文。
markdown
undefinedPrerequisites
前置条件
Before you begin, ensure you have:
- Node.js 18 or later installed
- An active account with admin permissions
- Your API key (find it in Settings > API)
undefined开始之前，请确保你已具备：
- 安装了Node.js 18或更高版本
- 具有管理员权限的有效账号
- 你的API密钥（在设置 > API中查找）
undefinedDefine Acronyms on First Use
首次出现时定义缩写
Spell out acronyms the first time they appear on a page.
markdown
<!-- Good -->
The CLI (Command Line Interface) provides tools for managing your resources.
Subsequent uses can just say "CLI."
<!-- Avoid -->
The CLI provides tools for managing your resources.在页面中首次出现缩写时拼写完整。
markdown
<!-- 推荐写法 -->
CLI（Command Line Interface，命令行界面）提供了管理资源的工具。
后续使用可直接称为“CLI”。
<!-- 避免写法 -->
CLI提供了管理资源的工具。Provide Complete, Runnable Code Examples
提供完整、可运行的代码示例
Code examples should work when copied. Include:
- All necessary imports
- Realistic placeholder values
- Expected output (when helpful)
markdown
<!-- Good: Complete example -->
```python
import requests
API_KEY = "your-api-key"
BASE_URL = "https://api.example.com/v1"
response = requests.get(
f"{BASE_URL}/users",
headers={"Authorization": f"Bearer {API_KEY}"}
)
print(response.json())代码示例复制后应能直接运行。需包含：
- 所有必要的导入语句
- 贴近实际的占位符值
- 预期输出（如有帮助）
markdown
<!-- 推荐写法：完整示例 -->
```python
import requests
API_KEY = "your-api-key"
BASE_URL = "https://api.example.com/v1"
response = requests.get(
f"{BASE_URL}/users",
headers={"Authorization": f"Bearer {API_KEY}"}
)
print(response.json())Output: {"users": [{"id": 1, "name": "Alice"}, ...]}
输出: {"users": [{"id": 1, "name": "Alice"}, ...]}
<!-- Avoid: Incomplete snippet -->
```python
response = requests.get(url, headers=headers)undefined
<!-- 避免写法：不完整的代码片段 -->
```python
response = requests.get(url, headers=headers)undefinedWrite Descriptive Titles and Meta Descriptions
撰写具有描述性的标题和元描述
Page titles and descriptions help with search and LLM understanding.
markdown
---
title: "Authentication - API Reference"
description: "Learn how to authenticate API requests using API keys, OAuth 2.0, or service accounts."
---页面标题和描述有助于搜索和LLM理解内容。
markdown
---
title: "Authentication - API Reference"
description: "Learn how to authenticate API requests using API keys, OAuth 2.0, or service accounts."
---Pitfalls to Avoid
需避免的误区
Don't Use Product-Centric Language
避免以产品为中心的表述
Orient documentation around user goals, not product features.
markdown
<!-- Good: User-goal oriented -->围绕用户目标而非产品功能来组织文档。
markdown
<!-- 推荐写法：以用户目标为导向 -->Send Emails
发送邮件
Send transactional emails to your users with delivery tracking.
<!-- Avoid: Product-centric -->向你的用户发送带有投递追踪的事务性邮件。
<!-- 避免写法：以产品为中心 -->Email Service
邮件服务
Our powerful email service provides enterprise-grade delivery.
undefined我们强大的邮件服务提供企业级投递能力。
undefinedSkip Obvious Instructions
跳过显而易见的操作说明
Don't document self-explanatory UI actions.
markdown
<!-- Good: Meaningful instruction -->
Enter your webhook URL. The URL must use HTTPS and be publicly accessible.
<!-- Avoid: Obvious instruction -->
Click in the text field. Type your webhook URL. Click the Save button.无需记录不言自明的UI操作。
markdown
<!-- 推荐写法：有意义的说明 -->
输入你的Webhook URL。该URL必须使用HTTPS且可公开访问。
<!-- 避免写法：冗余的操作说明 -->
点击文本框。输入你的Webhook URL。点击保存按钮。Avoid Colloquialisms
避免口语化表达
Colloquialisms hurt clarity and localization.
markdown
<!-- Good -->
This approach significantly improves performance.
<!-- Avoid -->
This approach is a game-changer for performance.
This will blow your mind.
Let's dive in!口语化表达会影响清晰度和本地化效果。
markdown
<!-- 推荐写法 -->
这种方法能显著提升性能。
<!-- 避免写法 -->
这种方法对性能来说是颠覆性的。
这会让你大吃一惊。
让我们深入了解！Quick Reference Checklist
快速参考检查表
When writing documentation, verify:
- Using "you" instead of "the user"
- Active voice throughout
- No unnecessary words
- Headings are descriptive
- Page is self-contained
- Proper heading hierarchy
- One term per concept
- Prerequisites listed
- Acronyms defined
- Code examples are complete
- No product-centric language
- No colloquialisms
撰写文档时，请验证以下内容：
- 使用“你”而非“用户”
- 全程使用主动语态
- 无冗余词汇
- 标题具有描述性
- 页面独立完整
- 标题层级正确
- 同一概念使用统一术语
- 列出了前置条件
- 定义了缩写
- 代码示例完整
- 无产品为中心的表述
- 无口语化表达
Applying This Skill
如何应用本指南
Use these principles when:
- Writing new documentation: Apply all principles from the start
- Reviewing documentation: Check against the quick reference checklist
- Editing existing docs: Prioritize voice/tone, then structure, then consistency
- Creating code examples: Ensure they are complete and runnable
在以下场景中使用这些原则：
- 撰写新文档: 从一开始就应用所有原则
- 审核文档: 根据快速参考检查表进行检查
- 编辑现有文档: 优先优化语气措辞，然后是结构，最后是一致性
- 创建代码示例: 确保示例完整且可运行