developer-docs-drafting

开发者文档撰写

使用此技能撰写开发者文档，让读者能够快速浏览、按步骤操作并加以应用。它会将受众和计划背景转化为清晰的页面结构和实用的文案。

此技能源自 Docs for Developers: An Engineer's Field Guide to Technical Writing，尤其是第 3 章“撰写文档”。其中还扩展了 Christopher Gales 和 Splunk Documentation Team 的 The Product Is Docs: Writing Technical Documentation in a Product Development Group 中经过转述的指导，尤其是第 9 章“学习目标”、第 14 章“场景驱动的信息开发”和第 25 章“编写 SaaS 文档”。请勿将书中的原文复制到用户输出中。来源：https://link.springer.com/book/10.1007/978-1-4842-7217-6

快速入门

1. 加载 guidelines.md，选择最精简且实用的参考资料集。
2. 确认受众、文档类型、一个主要读者目标，以及可用的学习目标。
3. 先拟定大纲再起草；将大纲视为文档的伪代码。
4. 撰写完整页面时使用 workflows/draft-developer-doc.md。
5. 将最重要的信息放在前面，并让页面便于快速浏览。

默认输出

撰写文档时，请返回：

1. 标题 - 与读者目标一致。
2. 开篇背景 - 读者将完成什么，以及所需的前提条件。
3. 结构化正文 - 根据需要安排标题、步骤、概念、示例、列表和提示框。
4. 场景或路径 - 在适用时，提供真实场景中的路径、范围边界或自成一体的主题背景。
5. 验证或预期结果 - 说明读者如何确认任务已成功完成。
6. 后续步骤 - 指明读者接下来应前往何处。
7. 草稿备注 - 列出假设、待办事项或需要审核的来源详情。

目录

需求	从这里开始
了解撰写文档的组成部分	references/core/knowledge.md
应用撰写规则	references/core/knowledge.md
查看前后对比示例	references/core/knowledge.md
撰写页面	workflows/draft-developer-doc.md
按任务选择路径	guidelines.md

核心原则

• 围绕读者的下一步决策或行动来撰写。
• 让读者即使快速浏览也能理解页面内容。
• 确保操作步骤可执行、可验证。
• 编写场景文档时，先讲用户遇到的问题，而非产品功能。
• 使用模板来减少从空白页面开始撰写的工作量，而不是强迫所有文档采用相同的形式。