Reference 类型文档写作规范
定义
Reference 是查询导向的文档，提供准确、完整、易查找的技术信息。
核心特征
| 特征 | 说明 | 对比 Explanation |
|---|---|---|
| 目的 | 快速查找具体信息 | 理解概念和原理 |
| 阅读方式 | 跳跃式、搜索式 | 顺序阅读 |
| 语言风格 | 精确、技术性 | 通俗、叙述性 |
| 结构要求 | 高度规范、可预测 | 灵活、自然流动 |
| 内容深度 | 完整但简洁 | 深入且有上下文 |
适用场景
✅ 应该写 Reference
- API 接口文档
- 配置参数说明
- 命令行工具手册
- 数据字典
- 错误代码表
- 术语表/词汇表
- 规范标准细则
- 字段定义
❌ 不该写 Reference
- 概念解释 → 写 Explanation
- 操作步骤 → 写 How-to
- 学习教程 → 写 Tutorial
- 背景介绍 → 写 Explanation
结构规范
必需元素
markdown
# [文档标题]
## 快速索引
[提供页内导航或重要链接]
## 概述
[一句话说明这是什么]
## [主体内容]
[根据类型组织，见分类规范]
## 相关资源
[交叉引用、延伸阅读]
## 版本信息
[版本号、更新日期、兼容性]组织原则
可预测的结构
- 同类文档结构一致
- 读者知道在哪里找什么
- 不要创新结构
清晰的层级
- 最多4级标题
- 层级关系明确
- 避免跳级
有效的索引
- 提供多种查找方式
- 字母序、分类、重要性
- 考虑搜索关键词
格式要求
表格使用
Reference 大量使用表格，因为表格最适合展示结构化信息：
markdown
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| name | string | 是 | - | 用户名称 |
| age | number | 否 | 18 | 用户年龄 |列表使用
- 用于选项枚举
- 用于步骤说明（简短）
- 用于特性列表
代码块
javascript
// 必须有语言标识
// 代码要完整可运行
// 注释说明关键点特殊标记
必需可选- 用标签标识- 默认值 - 加粗显示
- 废弃 - 斜体标识
- ⚠️ 警告 - 用图标强调
常见 Reference 类型
Reference 文档可以规范各种内容：
技术规范
- API 接口规范
- 数据格式规范
- 协议规范
- 配置规范
代码规范
- 编码规范
- 命名规范
- 架构规范
- 测试规范
操作规范
- 命令行工具手册
- 操作手册
- 部署规范
- 维护规范
知识规范
- 术语表
- 数据字典
- 错误码表
- 标准定义
每种具体类型可以有自己的专门规范文档，但都遵循本文档定义的通用原则。
内容要求
完整性
- [ ] 列出所有参数/选项/字段
- [ ] 包含所有可能的值
- [ ] 说明所有约束条件
- [ ] 覆盖边界情况
准确性
- [ ] 类型信息正确
- [ ] 默认值准确
- [ ] 版本信息最新
- [ ] 示例可运行
简洁性
- 描述不超过2句话
- 示例最小化
- 不解释原理（链接到 Explanation）
- 不含冗余信息
语言规范
使用专业术语
- Reference 可以使用技术术语
- 但要在术语表中定义
- 首次出现可以简单解释
保持中性语气
- 不用"你"、"我们"
- 使用被动语态或祈使句
- 避免情感色彩
精确表达
- "必须"不是"应该"
- "默认"不是"通常"
- "无效"不是"可能出错"
质量标准
必须满足
- [ ] 可查找性：能通过多种方式快速定位
- [ ] 完整性：包含所有必要信息
- [ ] 准确性：信息正确无误
- [ ] 一致性：格式统一、术语一致
- [ ] 时效性：版本信息清晰
- [ ] 可验证性：示例可执行
建议包含
- [ ] 快速索引/目录
- [ ] 交叉引用
- [ ] 常见错误说明
- [ ] 版本差异说明
- [ ] 相关资源链接
必须避免
- [ ] 冗长的解释
- [ ] 个人观点
- [ ] 模糊的描述
- [ ] 过时的信息
- [ ] 不完整的示例
检查清单
写完后验证：
- 搜索测试：用关键词能否快速找到？
- 完整性测试：新手能否找到所有必需信息？
- 准确性测试：示例代码能否运行？
- 一致性测试：与其他同类文档格式是否一致？
- 维护性测试：下次更新容易找到修改点吗？
维护指南
版本控制
- 标注文档版本
- 记录重要变更
- 保留历史版本链接
定期审查
- 每季度检查准确性
- 同步代码变更
- 更新过时示例
反馈处理
- 设置反馈渠道
- 快速修正错误
- 记录常见问题
模板
基础模板
markdown
---
layer: [Layer]
type: Reference
title: [标题]
version: 1.0.0
date: YYYY-MM-DD
---
# [标题]
## 概述
[一句话说明]
## [主体内容]
[根据类型选择合适的组织方式]
## 参数/选项/字段
| 名称 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| | | | | |
## 示例
`[最小化示例代码]`
## 相关资源
- [相关文档1]
- [相关文档2]
## 版本信息
- **当前版本**: 1.0.0
- **更新日期**: YYYY-MM-DD
- **兼容性**: [说明]具体类型的规范
不同类型的 Reference 应该有自己的专门规范文档。例如：
- API 文档撰写规范
- 配置文档撰写规范
- 命令行文档撰写规范
- 术语表撰写规范
这些都是独立的 Reference 文档，定义各自领域的具体要求。
与其他类型的区别
| 对比项 | Reference | Explanation | How-to | Tutorial |
|---|---|---|---|---|
| 目的 | 查询信息 | 理解原理 | 解决问题 | 学习技能 |
| 阅读方式 | 跳跃查找 | 顺序阅读 | 按需阅读 | 跟随练习 |
| 内容组织 | 高度结构化 | 自然叙述 | 任务导向 | 步骤递进 |
| 语言风格 | 技术精确 | 通俗易懂 | 简洁明了 | 友好引导 |
| 示例作用 | 展示用法 | 帮助理解 | 解决问题 | 动手练习 |
本规范的定位
本文档是一个"元规范"（meta-reference），定义如何撰写各种规范文档的通用原则。
它本身也是一个 Reference 文档，严格遵循自己定义的原则：
- 高度结构化的组织
- 清晰的表格和列表
- 快速索引和导航
- 精确的技术语言
- 完整但简洁的信息
作为元规范，它不关注具体规范什么内容，而是关注规范文档应该如何组织和表达。
参考资源
- Diátaxis - Reference - Diátaxis 框架对 Reference 的官方定义
- API 文档最佳实践 - API 文档写作指南
- GNU 文档标准 - 经典的技术文档规范
记住：Reference 不是在"教学"，而是在"提供查询"。