把文档当作变更的一部分
当行为发生变化时，更新文档最可靠的时机是在同一个 Pull Request 中。评审者可以同时比对实现与说明，版本标签也能让文档与发布的代码保持一致。
- 在组件附近保留一份聚焦的 README。
- 当公开行为、配置或运维步骤发生变化时，要求同步更新文档。
- 在持续集成中使用链接和风格检查。
- 为高风险运行手册和参考页面指定明确的所有者。
写作前先确定文档类型
教程通过步骤序列进行教学。操作指南解决具体任务。参考资料描述精确行为。说明文档提供背景和权衡。把四种类型混入一个冗长的 README，会让每一种都更难使用。
架构决策记录是另一个有用的模式：趁思路还清晰时，记录背景、决策、备选方案和后果。Markdown 让记录与代码保持贴近，而无需单独的发布工作流。
让代码示例可测试且真实可靠
读者会复制示例。请包含所需的导入、真实的名字、预期输出以及相关的错误路径。如果代码片段是有意不完整的，请说明。一个经过测试的小示例，比一大段看似合理的代码块更有价值。
一个实用的命令示例Markdown
```bash # Validate docs before opening a pull request npm run lint npm run typecheck ``` Expected result: both commands exit with status 0.
为易于评审的差异而优化
只有当仓库统一采用一句一行的约定时才这样做；否则自然换行，让工具负责排版。在事实性修改时避免对整个文件重新排版。稳定的标题和参考式链接可以让大型文档更容易修改，而不产生杂乱的差异。
- 为标题赋予具体的名字，使其在生成的锚点中仍然有用。
- 保持表格窄而紧凑，避免大段文字塞满单元格。
- 对于随仓库一起移动的文件，使用相对链接。
- 不要在示例中粘贴密钥、私有日志或未经脱敏的生产数据。
把转换作为迁移的起点
Word 文件、电子表格、PDF 或演示文稿中可能包含尚未适配 docs-as-code 工作流的宝贵知识。将其转换为 Markdown 会去除大部分呈现层，但开发者仍需要规范化标题、修复链接、划分文件边界，并确认技术内容的准确性。
在转换版本被评审之前，请保留源文档。对于计算结果或签名记录，即使在仓库中加入了可读的 Markdown 快照，原件也可能仍然是唯一的事实来源。