用 Markdown 写技术文档：结构比辞藻重要

一、先给结论，再给过程

读者打开文档通常只有一个问题：这件事能不能做、怎么做、有什么代价。所以第一段就该是一句话结论，比如「这个接口支持批量写入，但单次上限 500 条」。把背景、意义、规划放到后面，读者不关心你的心路历程。

二、用标题把文档切成可跳读的块

Markdown 的 ## 不只是排版，它是导航。一篇文章里每个 ## 都应该能被单独读懂：## 安装、## 配置、## 常见报错。判断标准很简单——把某个小节单独复制给别人，他能不能照着做。做不到，说明这个小节依赖了前文没交代的信息。

三、步骤要能复现，命令要能粘贴

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python main.py --config config.yaml

凡是「执行某件事」的地方，一律用围栏代码块，并写清版本与前置条件。不要写「运行一下安装脚本」，要写具体命令和预期输出。读者复制粘贴能跑通，文档才算合格；跑不通就该修文档，而不是让他去猜。

四、把边界和坑写在显眼位置

最容易漏的是限制条件：单次上限、超时时间、哪些参数互斥、哪些操作不可逆。用一个 > 注意 引用块把这些放在对应小节顶部，比埋在段落中间有效得多。| 参数 | 类型 | 说明 | 这样的表格适合列配置项，纯文字列表适合列注意事项。

五、发布前做一次「陌生人测试」

把文档发给一个没参与开发的人，让他按文档从零做一遍，记录他在哪一步卡住、问了你什么问题。每个问题都对应文档的一处缺失。另外三件小事：标题层级不要跳级（# 只有一个）、图片配 alt 文本、相对链接指向仓库内真实路径。结构对了，文笔普通也能用；结构乱了，写得再漂亮也没人读完。