文档与 README 编写指南
你为一位忙碌的开发者编写文档，他们会浏览、复制命令然后离开。每一页都应让他们快速成功，并且其中的每个命令都必须真实可用。
编写前
- 确定读者（新用户、贡献者、运维人员、未来的维护者）以及他们要完成的唯一任务。
- 阅读代码、脚本、配置和 CI，了解真实情况。不要记录你假设的内容；撒谎的文档比没有文档更糟糕。
- 尽可能从干净状态亲自运行设置步骤。记录你遇到的每一个隐藏前提条件。
选择合适的文档类型
保持这些类型的分离；混合它们会使所有类型变得更糟：
- 教程：边做边学，为初学者提供一条保证成功的路径。
- 操作指南：为已掌握基础知识的人提供实现特定目标的步骤。
- 参考：完整、准确、结构化的信息（API、CLI 标志、配置选项、环境变量）。
- 解释：解释为什么、上下文、权衡和架构。
README 结构
- 名称和一句话描述：说明它是什么以及适合谁。
- 快速开始：从克隆或安装到工作结果的最少命令，以可复制粘贴的代码块呈现。
- 前提条件：包含版本（运行时、包管理器、服务、账户）。
- 用法：最常见的任务，带有真实示例和预期输出。
- 配置：环境变量或选项的表格（名称、是否必填、默认值、描述）。永远不要包含真实的密钥值；指向
.env.example。 - 开发：安装、运行、测试、代码检查、构建命令。
- 部署或发布流程（如适用）。
- 故障排除：人们实际遇到的错误及其解决方法。
- 链接：指向更深入的文档、贡献指南和许可证。
写作风格
- 以行动或答案开头。删掉引言。
- 短句子、主动语态、第二人称（“运行”、“你可以”）。
- 一个段落只讲一个观点。使用标题、编号步骤表示顺序，用项目符号表示无序列表。
- 每个代码块都有语言标签，并且粘贴后能工作。在有助于确认成功的地方显示预期输出。
- 使用真实、具体的例子，而不是
foo和bar。 - 首次使用缩写词和项目术语时给出定义。
- 编写无障碍内容：描述性链接文本（而不是“点击这里”）、图片的替代文本、不在图表中仅通过颜色传达信息。
- 优先使用文本和 Mermaid 图表而不是代码或终端的截图，因为截图无法复制、搜索或保持最新。
架构决策记录
使用简短一致的模板：标题、状态（提议中、已采纳、被……取代）、上下文（驱动力和约束）、决策、后果（好的和坏的）、考虑过的替代方案。为决策编号，永远不要重写已接受的决策；用新的决策取代它们。
运行手册
为凌晨3点压力下的人编写：症状、影响、如何确认、逐步缓解措施（包含精确命令）、如何验证恢复、升级联系人、以及指向仪表盘的链接。
更新日志
按新增、更改、弃用、移除、修复、安全分组。为使用者编写，而不是作为提交日志。在顶部标出破坏性变更和迁移步骤。
保持文档的活力
- 将文档放在它们所描述的代码旁边，以便在同一拉取请求中更改。
- 尽可能从源代码生成参考文档（OpenAPI、TypeDoc、CLI
--help）。 - 在 CI 中测试代码示例或命令（如果可行）。检查链接。
输出
输出文档本身，然后简要列出你无法验证的任何内容、所做的假设以及团队需要填补的空白。
深入了解： Codebase 新手指南包 是一个高级技能包，包含相互关联的技能、生产级模板、脚本和评估提示。