changan-su/forsion/document-writing-cn

中文文档写作

动笔前三问

1. 读者是谁:新人/维护者/决策者?决定详略——给新人多写背景和步骤,给维护者多写设计取舍,给决策者先写结论和影响。
2. 读完要能做什么:能跑起项目?能做技术决策?能接手维护?文档每一节都为这个目标服务,无关内容删。
3. 放在哪:先用 glob_files 看项目已有文档的位置与命名习惯,跟随现有惯例,不另起炉灶。

技术文档通用结构:背景 → 方案 → 细节 → 验证

# 标题(一句话说清主题)
 
## 背景
要解决什么问题、为什么现在做、不做的代价。2-4 句,新读者看完知道"为什么有这篇文档"。
 
## 方案
核心思路一段话讲清,再列关键决策。每个决策写"选了什么 + 为什么 + 放弃了什么备选"。
 
## 细节
接口/数据结构/流程图/配置项。代码与表格优先于大段文字。
 
## 验证
怎么证明它工作:测试方法、验收标准、已知局限。

原则:结论先行——每节第一句就是该节要点,细节往后放;读者扫一遍各节首句应能拼出全文大意。

中文排版规范(逐条执行)

• 中英文之间加空格:"使用 Docker 部署"而非"使用Docker部署";中文与数字之间同理:"耗时 3 秒"。
• 标点用全角:中文句子用「,。:;?!」;括号内全是英文/代码时可用半角括号。不混用——同一句不要出现 , 和 , 混排。
• 专有名词大小写跟随官方:GitHub、PostgreSQL、iOS、TypeScript;不要写成 github、Postgresql。
• 代码、命令、文件名、变量一律包反引号:npm run dev、config.ts。
• 术语一致:同一概念全篇用同一个词(选了"微后端"就不要又写"micro-backend 模块"混用);首次出现给出中英对照,如"功能开关(feature flag)"。
• 数字使用阿拉伯数字;百分号、单位紧跟数字:"提升 30%"、"超时 5s"。
• 链接写成有意义的文字:[部署文档](./deploy.md),不裸贴 URL。
• 列表项保持结构平行:都是动词开头或都是名词短语,不混。

常用模板

README

# 项目名 — 一句话定位
## 功能特性(3-6 条,用户视角)
## 快速开始(从零到跑起来的最短命令序列,逐条可复制执行)
## 配置(环境变量表:名称 | 必填 | 默认值 | 说明)
## 目录结构(只列关键目录,各加一句说明)
## 常见问题 / 开发指引(可选)

快速开始必须亲手验证过:命令逐条用 run_bash 跑通再写进文档。

设计文档

按"背景 → 目标与非目标 → 方案(含架构图/数据流)→ 备选方案对比 → 风险与回滚 → 里程碑"组织。非目标一节不可省,明确不做什么能避免范围蔓延。

开发日志(Log)

## {YYYY-MM-DD} — {简要描述}
### 变更
-做了什么、为什么这样做(写动机与取舍,不复述 commit message)
### 备注
-修改既有实现时标注:> 修订:{日期} — {原条目} — 改了什么

写作与修订流程

1. 先用 read_file 读 1-2 篇项目内同类文档,对齐语气、格式、标题层级。
2. 列出大纲(各节标题加一句话要点),结构对了再填内容。
3. 写完自查清单:

• 通读一遍,删掉不影响理解的句子(通常能删 20%);
• 检查排版规范逐条过(空格、标点、术语);
• 文中命令/代码片段实际执行验证;
• 文内链接和文件路径用 glob_files 确认存在;
• 标题层级连续(h2 下不直接跳 h4)。

1. 修改他人文档时保持最小 diff:跟随原文风格,不顺手重排无关段落。

详略裁剪法

• 教程类:步骤完整到"复制粘贴就能成功",每步给出预期输出。
• 参考类:表格化、可检索,不写心路历程。
• 决策类:第一屏给结论、影响、所需行动;论证放附录。
• 日志类:写"为什么",代码细节留给 diff 本身。
• 任何类型:与主题无关的实现八卦、过程曲折,一律不写。