📐 技术写作与文档规范

1. 技术写作的核心原则

技术写作不同于文学创作——它的目标是传递信息，而非展示文采。好的技术文档像一份精确的导航地图，让读者以最短路径找到答案。

🎯 清晰

一个句子只表达一个意思。避免模糊词汇（"可能""大概""一般"）。

⚡ 简洁

删掉每个不必要的词。能用5个字说清的事，不要用20个字。

✅ 准确

数据、版本号、命令必须精确。错误的文档比没有文档更糟糕。

2. 文档结构黄金模板

无论是API文档、操作手册还是设计文档，都可以套用这个五段式结构：

📄 通用技术文档结构模板

============================================
   [文档标题] - 一句话说明本文档的用途
   版本：v1.0 | 作者：张三 | 日期：2026-05-28
============================================

【一、概述】（Overview）
用 2-3 句话回答：这份文档写给谁？解决什么问题？
示例：本文档面向后端开发人员，描述了订单模块
      的API接口规范，包括请求格式、参数说明和响应示例。

【二、前置知识】（Prerequisites）
读者需要提前了解什么？
- 熟悉 RESTful API 基本概念
- 已阅读《系统架构概述》（链接）
- 开发环境已配置 Java 17 + Maven 3.8+

【三、正文】（Main Content）
按逻辑顺序组织内容：
3.1 [子主题1]
3.2 [子主题2]
3.3 [子主题3]

每个子主题包含：
- 概念解释（是什么）
- 操作步骤（怎么做）
- 代码示例（长什么样）
- 注意事项（坑在哪）

【四、示例/案例】（Examples）
提供至少一个完整、可运行的端到端示例。
❌ 错误：给出零散的代码片段
✅ 正确：给出从配置到运行的完整流程

【五、常见问题】（FAQ / Troubleshooting）
预判读者可能遇到的5个以上问题：
Q1: 接口返回401怎么办？
A1: 检查Token是否过期，重新获取后重试。

Q2: 为什么订单状态一直是"处理中"？
A2: 可能是异步回调未触发，手动调用 /order/refresh 接口。

【六、参考资源】（References）
- API 完整参考：[链接]
- 相关设计文档：[链接]
- 变更日志：[链接]

3. 技术术语与命名规范

场景	规范	✅ 正确	❌ 错误
首次出现的术语	给出全称+缩写	应用程序编程接口（API）	直接用API不加解释
代码中的变量	小驼峰命名	`orderStatus`	`order_status`（Java）
数据库字段	下划线命名	`created_at`	`createdAt`（MySQL）
API路径	名词复数 + 小写	`/api/v1/orders`	`/api/v1/getOrderList`
版本号	语义化版本	`v2.1.3`	`v2.1.3-final-new`
按钮/菜单文案	动词 + 名词	"提交订单"	"点这里提交"

4. Markdown 写作规范（技术文档首选格式）

📄 Markdown 写作模板

# 一级标题（仅用于文档标题，全文只有一个）

## 二级标题（章节标题）

### 三级标题（子章节）

**加粗** 用于强调关键概念、按钮名称、重要提示
*斜体* 用于引入新术语、引用他人说法

`行内代码` 用于：文件名、变量名、命令、状态值

> 引用块用于：重要提示、注意事项、警示信息

有序列表用于步骤说明：
1. 第一步：打开配置文件 `application.yml`
2. 第二步：修改 `server.port` 为 8080
3. 第三步：执行 `mvn spring-boot:run`

无序列表用于并列项：
- 功能A：支持批量导入
- 功能B：支持实时推送
- 功能C：支持多租户隔离

| 表格 | 用于 | 对比 |
|------|------|------|
| 左对齐 | 默认 | 文本 |

三个反引号 + 语言标识符用于代码块：
```java
public class OrderService {
    public Order createOrder(OrderRequest req) {
        // 关键逻辑
    }
}
```

【Markdown 写作铁律】
1. 标题层级不跳号（一级→二级→三级）
2. 代码块必须标注语言（java / python / json / bash）
3. 链接使用有意义的文字，避免"点击这里"
4. 每个段落不超过5行，行宽不超过120字符

5. 文档评审检查清单

📄 文档发布前自检清单

【内容完整性】
☐ 是否明确定义了目标读者和技术门槛？
☐ 是否包含至少一个完整的端到端示例？
☐ 是否覆盖了常见的错误场景和解决方案？
☐ 所有外部链接是否有效？

【可读性】
☐ 每个段落是否只表达一个核心观点？
☐ 是否使用了主动语态（"点击按钮" > "按钮被点击"）？
☐ 是否避免了长句（一句话不超过40个汉字）？
☐ 是否使用了截图/图示来辅助复杂概念？

【准确性】
☐ 代码示例是否经过实际运行验证？
☐ 版本号和日期是否已更新？
☐ API 参数、返回值是否与实际一致？
☐ 废弃内容是否已标注（@Deprecated）？

【一致性】
☐ 术语使用是否全文统一？
☐ 格式（标题、编号、代码样式）是否一致？
☐ 中英文混排是否加空格？（"使用 Git 管理代码"）

【可维护性】
☐ 是否标注了最后更新日期和作者？
☐ 是否有变更日志（Changelog）？
☐ 文档存放位置是否在团队约定的位置？

6. 技术写作常见误区与纠正

误区	示例	纠正
知识诅咒	假定读者懂得你懂的背景知识	每引入一个新概念，先给一句定义或链接
流水账式	"然后点这里，然后输这个，然后..."	用编号步骤 + 明确的"为什么"解释每一步
过度技术化	对非技术读者使用大量术语	区分读者群体，对非技术读者降低术语密度
缺乏上下文	直接贴一段代码而不说它解决什么问题	代码前先写一句"这段代码用于..."
假设完美环境	不写权限、网络、依赖等前置条件	单独列出"前置条件"小节

💡 写作自测法写完文档后，找一个不熟悉该领域的同事阅读。如果他能不提问就理解并操作成功，你的文档就是合格的。如果他要追问3个以上的问题，请回去修改。

7. 文档类型速查

设计文档

技术设计文档

架构设计、技术选型、接口定义、数据模型。读者：开发团队。

API文档

接口文档

端点、参数、返回值、错误码、示例。读者：调用方开发。

操作手册

运维/操作手册

部署步骤、配置说明、故障处理。读者：运维/支持团队。

发布说明

Release Notes

版本新功能、修复问题、已知问题、升级注意事项。读者：全体用户。

快速入门

Quick Start

5分钟上手，最小化配置跑通示例。读者：新用户。

常见问题

FAQ

高频问题与答案，按主题分类。读者：所有遇到问题的用户。

← 上一页：测试知识沉淀方法返回知识库首页 →

📐 技术写作与文档规范 · 写作模板系列