documentation

---
name: documentation
description: 生成和维护清晰、准确的技术文档。当需要编写 README、模块/API 说明、设计文档、ADR（架构决策记录）、变更日志，或统一写作结构与规范时使用。
---

# 技术文档撰写

以结构清晰、面向读者、可长期维护为目标的文档编写方法。

## 谁是读者，决定深度
先明确文档给谁看、解决什么问题：
- **README**：使用者 —— 怎么装、怎么跑、怎么用、有哪些命令。
- **API/模块说明**：集成者 —— 签名、参数、返回值、示例、错误。
- **设计文档/ADR**：团队 —— 为什么这么设计、权衡、备选方案。
- **变更日志**：所有用户 —— 版本间行为变化。

## 通用结构模板

### README 模板
```markdown
# 项目名
一句话说明做什么、解决什么问题。

## 特性
- ...

## 安装 / 环境要求
- 依赖、版本、环境变量。

## 快速开始
- 最小可运行示例（从零到跑起来）。

## 使用说明 / 命令
- 常用命令清单。

## 配置
- 配置文件与字段含义。

## 项目结构
- 目录树 + 每个关键目录职责（可选）。

## 测试 / 构建
- 如何跑测试与构建。

## 常见问题
- FAQ。
```

## 编写原则
- **少即是多**：文档也是代码，需要维护，只写必要内容。
- **从例入手**：能用一个可运行示例讲清楚的，优先示例。
- **说明“为什么”**：接口/结构背后的动机比一堆“是什么”更有价值。
- **命令可直接复制**：给出可复制可运行的命令。
- **避免过时**：凡是代码能自解释的，别在文档里重复，并标明“以代码为准”。
- **版本与日期**：文档标明适用版本、最近更新时间。

## ADR（架构决策记录）模板
```markdown
# ADR-NNN: <决策标题>

## 状态
提议中 / 已接受 / 已废弃

## 背景
要解决什么问题，面临什么约束。

## 决策
我们选择怎么做。

## 备选方案
考虑过但放弃的选项与放弃原因。

## 后果
正面与负面影响、权衡、迁移成本。
```

## 文档发布要点
- 建立目录（TOC），长文档便于跳转。
- 使用一致标题层级与命名规范。
- 图片/图表说明替代不了的复杂关系（嵌入或外链）。
- 完成后通读一遍，检查命令与示例是否真实可运行。