文档风格指南

在撰写或审阅文档时，请应用以下原则，以确保内容对人类读者和大语言模型（LLM）均具备清晰性、一致性和可访问性。

首先选择合适的文档类型

写作风格服务于特定目的，而该目的取决于您所撰写的四种 Diataxis 文档类型中的哪一种。在应用下方各项规范之前，请先明确当前文档属于以下哪一类：教程（Tutorial）（面向学习）、操作指南（How-To Guide）（面向任务）、参考文档（Reference）（面向查询），还是解释说明（Explanation）（面向理解）。这四类文档不可互换；在同一文档中混用会削弱每种类型的效力。

判断时，请回答两个“指南针问题”：侧重行动还是认知？侧重习得还是应用？

如需完整的决策流程、2×2 分类图、可解决大多数歧义的两个关键区分维度（教程 vs. 操作指南，参考文档 vs. 解释说明），以及质量模型，请参阅 references/diataxis-compass.md。一旦确定文档类型，即可基于本指南中的原则，进一步运用类型专属技能（tutorial-docs、howto-docs、reference-docs、explanation-docs）。

语气与语调

使用第二人称

直接以“你”称呼读者，而非“用户”或“开发者”等泛称。

你可以通过设置环境变量来配置 API。


用户可以通过设置环境变量来配置 API。
开发者应通过设置环境变量来配置 API。

优先使用主动语态

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

在根目录下创建一个配置文件。
该函数返回一个用户对象数组。


应在根目录下创建一个配置文件。
该函数返回一个用户对象数组。

保持简洁

删减冗余词汇。每个词都应有其存在价值。

运行安装命令。


为继续操作，你需要运行安装命令。

该端点返回用户数据。


该端点用于返回用户数据。

常见可简化短语：

文档结构

撰写清晰、具描述性的标题

标题应准确传达本节内容。避免使用俏皮或含糊的标题。

## 安装 CLI
## 配置认证
## 处理速率限制


## 入门指南（含糊）
## 有趣的部分（俏皮）
## 其他（无信息量）

构建自包含页面

假设读者可能通过搜索引擎直接访问任一页面。因此，每一页都应做到：

• 阐明该功能/概念是什么
• 清晰列出前提条件
• 为该主题提供完整上下文

# Webhook

Webhook 可在你的账户中发生事件时，向你推送实时通知。

## 前提条件

- 具备 Webhook 权限的有效 API 密钥  
- 一个可公开访问的 HTTPS 端点

## 创建 Webhook

...

使用语义化标记

根据内容类型选用恰当格式：

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

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| api_key | string | 是 | 你的 API 密钥 |
| timeout | integer | 否 | 请求超时时间（秒） |


要完成认证，你可以：
- 在请求头中使用 API 密钥
- 使用 OAuth 2.0
- 使用服务账号

提升内容可扫读性

将密集段落拆分为易于消化的小块：

• 每段控制在 3–4 句以内
• 用项目符号罗列条目
• 长章节中添加子标题
• 把关键信息前置（倒金字塔结构）

## 错误处理

API 返回标准 HTTP 状态码。

### 常见错误

- **400 Bad Request**：参数无效。请检查请求体。
- **401 Unauthorized**：API 密钥无效或缺失。
- **429 Too Many Requests**：超出速率限制。请等待后重试。

### 重试策略

针对 429 错误，请采用指数退避策略，初始等待时间为 1 秒。

一致性

每个概念仅使用一个术语

选定术语后须始终如一地使用。术语切换会使读者困惑。

在控制台中生成 API 密钥。在 Authorization 请求头中使用你的 API 密钥。


在控制台中生成 API 密钥。在 Authorization 请求头中使用你的 API token。

请记录术语选用规范：

保持格式统一

对同类内容使用相同格式：

• UI 元素：加粗（单击 保存）
• 代码/命令：反引号包裹（npm install）
• 文件路径：反引号包裹（/etc/config.yaml）
• 首次出现的关键术语：加粗或斜体
• 占位符：全大写加下划线（SCREAMING_CASE）或尖括号（YOUR_API_KEY 或 ）

面向 LLM 友好的写作模式

明确陈述前提条件

清晰列出用户开始前必须满足的条件。此举有助于人类读者与 LLM 共同理解上下文。

## 前提条件

开始前，请确认已满足以下条件：

- 已安装 Node.js 18 或更高版本  
- 拥有具备管理员权限的有效账户  
- 已获取你的 API 密钥（可在 **Settings > API** 中找到）

首次使用缩略语时给出全称

缩略语在页面中首次出现时，须拼写出完整形式。

CLI（Command Line Interface）提供了用于管理资源的工具。
后续出现可直接简称为“CLI”。


CLI 提供了用于管理资源的工具。

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

代码示例应支持直接复制运行。务必包含：

• 所有必需的导入语句
• 符合实际的占位符值
• 预期输出（必要时）

```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())
# 输出: {"users": [{"id": 1, "name": "Alice"}, ...]}

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

### 撰写具描述性的标题与元描述

页面标题与描述有助于搜索优化及 LLM 理解。

```markdown
---
title: "认证 - API 参考文档"
description: "了解如何使用 API 密钥、OAuth 2.0 或服务账号对 API 请求进行认证。"
---

应避免的误区

勿使用以产品为中心的语言

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

# 发送邮件

向你的用户发送事务性邮件，并支持投递状态追踪。


# 邮件服务

我们强大的邮件服务提供企业级投递能力。

跳过显而易见的操作说明

无需描述用户一看即懂的 UI 操作。

输入你的 webhook URL。该 URL 必须使用 HTTPS 协议且可被公网访问。


单击文本框。输入你的 webhook URL。单击“保存”按钮。

避免口语化表达

口语化表达损害清晰度与本地化适配能力。

该方法显著提升了性能。


该方法是性能方面的“游戏规则改变者”。
这会让你大吃一惊。
让我们深入探讨！

两类质量维度

优质文档具备两层质量，且第二层质量依赖于第一层：

• 功能性质量——客观、可衡量：准确性、完整性、一致性、实用性、精确性。这是基础前提。本指南所述原则及各类型专属技能，均聚焦于提升功能性质量。
• 深层质量——主观、以人为本：使用体验良好、能预判读者需求、契合真实工作方式。若缺乏功能性质量，则无法抵达深层质量；而正确选择文档类型（如上所述）并干净利落地完成撰写，正是实现深层质量的前提条件。

完整质量模型及“渐进式改进”方法（每次只改进一个真实内容模块，绝不预先搭建空章节骨架），详见 references/diataxis-compass.md。

快速核对清单

撰写文档时，请逐项核查：

• 文档严格归属某一 Diataxis 类型，未混合类型（参见指南针）
• 使用“你”，而非“用户”
• 全文使用主动语态
• 无冗余词汇
• 标题具描述性
• 页面自包含
• 标题层级正确
• 每个概念仅使用一个术语
• 明确列出前提条件
• 缩略语已定义
• 代码示例完整可运行
• 无以产品为中心的语言
• 无口语化表达

本技能的应用场景

请在以下情形中应用上述原则：

1. 撰写新文档：从一开始就全面应用所有原则
2. 审阅文档：对照快速核对清单逐项检查
3. 修订现有文档：优先调整语气/语调，其次优化结构，最后统一术语与格式
4. 编写代码示例：确保其完整且可直接运行