docs-style

文档风格指南

编写或审核文档时，请遵循以下原则，确保内容清晰、一致且易于人类读者和大模型理解。

首先选择合适的文档类型

风格服务于目的，而目的取决于你正在撰写 Diataxis 的四种类型中的哪一种。在应用以下规范之前，先判断文档属于 教程（学习）、操作指南（完成任务）、参考（查找信息）还是 说明（理解原理）——这些类型不可互换，在同一份文档中混用会削弱它们各自的效果。

选择时，请思考指南针的两个问题：行动还是认知？习得还是应用？

读者的立场	类型
“我正在学习——请指导我操作”	教程
“我有一个目标——请帮我实现”	操作指南
“我正在工作——让我查找所需信息”	参考
“我正在思考——请帮我理解原因”	说明

如需了解完整的决策流程、2×2 矩阵、解决大多数歧义的两项区分（教程与操作指南、参考与说明），以及质量模型，请参阅 references/diataxis-compass.md。选择类型后，特定类型的技能（tutorial-docs、howto-docs、reference-docs、explanation-docs）会基于本指南中的原则进行扩展。

语态与语气

使用第二人称

直接称呼读者为“你”，而不是“用户”或“开发者”。

You can configure the API by setting environment variables.


The user can configure the API by setting environment variables.
Developers should configure the API by setting environment variables.

优先使用主动语态

让句子的主语执行动作。主动语态更清晰、直接。

Create a configuration file in the root directory.
The function returns an array of user objects.


A configuration file should be created in the root directory.
An array of user objects is returned by the function.

简洁明了

删掉不必要的词。每个词都应发挥作用。

Run the install command.


In order to proceed, you will need to run the install command.

This endpoint returns user data.


This endpoint is used for the purpose of returning user data.

可简化的常见表达：

替代	使用
为了	来，以便
为……的目的	来，为了
在……的情况下	如果
在这个时间点	现在
由于……这一事实	因为
有必要	必须
能够	可以
加以利用	使用

文档结构

编写清晰、具体的标题

标题应明确说明该部分的内容。避免巧妙或含糊的标题。

## Install the CLI
## Configure Authentication
## Handle Rate Limits


## Getting Started (vague)
## The Fun Part (clever)
## Misc (uninformative)

创建自成一体的页面

假设读者可能会从搜索结果直接进入任意页面。每个页面都应：

• 解释功能或概念是什么
• 清楚说明前置条件
• 提供主题所需的完整背景信息

# Webhooks

Webhooks let you receive real-time notifications when events occur in your account.

## Prerequisites

- An active API key with webhook permissions
- A publicly accessible HTTPS endpoint

## Create a Webhook

...

使用语义标记

根据内容类型选择合适的格式：

• 标题：遵循正确的层级结构（h1 > h2 > h3，不要跳级）
• 列表：用于列出多个相关项目
• 表格：用于展示属性一致的结构化数据
• 代码块：用于展示任何代码、命令或文件路径

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| api_key | string | Yes | Your API key |
| timeout | integer | No | Request timeout in seconds |


To authenticate, you can:
- Use an API key in the header
- Use OAuth 2.0
- Use a service account

让内容便于浏览

将冗长的段落拆分成易于理解的小块：

• 每段最多 3-4 句话
• 使用项目符号列出项目
• 为较长的章节添加小标题
• 将关键信息放在前面（倒金字塔结构）

## Error Handling

The API returns standard HTTP status codes.

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

### Retry Strategy

For 429 errors, use exponential backoff starting at 1 second.

一致性

每个概念使用一个术语

选定一个术语并始终保持一致。切换术语会让读者困惑。

Generate an API key in the dashboard. Use your API key in the Authorization header.


Generate an API key in the dashboard. Use your API token in the Authorization header.

记录术语选择：

概念	使用	不要使用
身份验证凭据	API key	API token、secret key、access key
配置文件	config file	settings file、preferences file
命令行	CLI	terminal、command prompt、shell

保持格式一致

相似类型的内容应使用相同的格式：

• UI 元素：加粗（点击 Save）
• 代码/命令：使用反引号（npm install）
• 文件路径：使用反引号（/etc/config.yaml）
• 首次出现的关键词：加粗或斜体
• 占位符：使用大写蛇形命名或尖括号（YOUR_API_KEY 或 <api-key>）

适合大模型理解的模式

明确说明前置条件

列出用户开始前所需的内容。这有助于人类和大模型理解上下文。

## Prerequisites

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**)

首次使用时定义缩写

缩写首次出现在页面时，请写出其全称。

The CLI (Command Line Interface) provides tools for managing your resources.
Subsequent uses can just say "CLI."


The CLI provides tools for managing your resources.

提供完整、可运行的代码示例

代码示例应可直接复制使用。请包含：

• 所有必需的导入
• 符合实际情况的占位值
• 预期输出（适用时）

```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"}, ...]}

response = requests.get(url, headers=headers)

### Write 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."
---

应避免的陷阱

不要使用以产品为中心的语言

围绕用户目标组织文档，而不是围绕产品功能。

# Send Emails

Send transactional emails to your users with delivery tracking.


# Email Service

Our powerful email service provides enterprise-grade delivery.

省略显而易见的说明

不要记录不言自明的 UI 操作。

Enter your webhook URL. The URL must use HTTPS and be publicly accessible.


Click in the text field. Type your webhook URL. Click the Save button.

避免使用口语表达

口语表达会影响清晰度和本地化效果。

This approach significantly improves performance.


This approach is a game-changer for performance.
This will blow your mind.
Let's dive in!

质量的两个层面

优秀的文档有两个质量层面，第二个层面取决于第一个：

• 功能质量——客观且可衡量：准确性、完整性、一致性、实用性和精确性。这是前提。本指南中的原则和针对不同文档类型的技能旨在提升功能质量。
• 深层质量——主观且以人为本：文档用起来让人感觉良好，能预见读者的需求，并契合人们的实际工作方式。没有功能质量，就无法实现深层质量；选择合适的文档类型（见上文）并清晰写作，才能为此创造条件。

完整的质量模型和“通过改进开展工作”的方法（一次改进一处实际内容；绝不搭建空洞的章节框架），请参阅 references/diataxis-compass.md。

快速参考清单

编写文档时，请确认：

• 文档属于一种明确的 Diataxis 类型，而非混合类型（参见类型指南）
• 使用“你”，而不是“用户”
• 全文使用主动语态
• 没有不必要的词语
• 标题具有描述性
• 页面内容完整自洽
• 标题层级正确
• 一个概念只使用一个术语
• 列出前提条件
• 定义缩写
• 代码示例完整
• 不使用以产品为中心的语言
• 不使用口语表达

应用此技能

在以下情形中运用这些原则：

1. 编写新文档：从一开始就应用所有原则
2. 审阅文档：对照快速参考清单进行检查
3. 编辑现有文档：优先处理语态和语气，然后是结构，最后是一致性
4. 创建代码示例：确保示例完整且可运行