--- name: writing-doc description: "编写、改写和审阅技术文档，包括 README、操作指南、教程、API 说明和设计说明。适用于改善文档结构、可读性、示例和读者完成任务的能力；不用于营销文案、文学创作或单纯的文件排版转换。" --- # Writing Doc 让读者快速找到答案，准确理解内容，并完成任务。以读者的需要决定结构和细节，不为满足写作规则增加负担。 本 skill 主要依据用户提供的《What makes documentation good》。原文标注为归档内容；沿用其写作原则，不把其中的模型、API 或术语示例当作当前技术事实。 ## 先确定读者要解决的问题 - 从请求、现有文档和项目资料判断读者、目标、已有知识与使用场景。仅在缺失信息会明显改变结果时提问。 - 遵循用户指定的语言、范围、格式和风格。修改已有文档时，保留正确事实、必要限定、有效链接和有意设置的结构。 - 优先解决常见且影响大的问题。不要为了覆盖所有读者而加入无关的入门教程或罕见边界情况。 - 根据任务直接写作、改写或审阅。用户只要求审阅时，指出具体问题及改法，不擅自改动文件。 ## 让读者扫读时也能找到答案 - 把答案、结论或关键行动放在文档和章节前面。说明结果时，先给结果，再解释方法。不要用悬念铺垫信息。 - 用标题划分有意义的内容。优先让标题表达具体问题、行动或结论，避免只有“概述”“结果”等抽象名词。保留 API 名称等便于查找的标准标题。 - 对较长、需要跨章节查找的文档提供目录。短文档不必添加目录。 - 让章节和段落的首句独立表达主题。把主题词放在靠前的位置，避免以“在此基础上”“如上所述”开头。 - 保持段落简短，一段只讲一个主题。关键结论可以单独成段。 - 并列信息用列表，顺序操作用编号，比较或对应关系用表格。保留适合连续阅读的解释性段落。 - 有选择地加粗关键结论、条件或行动。不要让整段加粗削弱重点。 ## 降低理解句子的负担 - 使用短句、主动语态和具体动词。删除无用的副词、重复修饰和过渡语，但保留条件、单位与必要限定。 - 在操作步骤中直接说明动作。避免推测读者心理，例如“现在你一定想知道”或“接下来你必须先学会”。 - 优先选择读者能一次理解的句式，不为缩短字数制造歧义。拆开含糊的名词串和过长的修饰语。 - 先交代目的或必要条件，再列出细节。避免让读者读到句末才能知道前面一长串内容的用途。 - 当“这”“它”“上述内容”可能指向多个对象，或需要跨段回忆时，重复具体名称。无需机械删除所有代词。 - 同一概念使用同一名称。统一大小写、标点、文件命名和示例风格，并遵循项目已有约定。 - 保持用户的语言。中文使用自然、明确的中文表达，不套用英语语法和词数限制。 ## 帮助不同背景的读者完成任务 - 用简单语言解释复杂概念，不删掉理解和正确操作所需的技术细节。不要假设某领域的专家也熟悉当前工具链。 - 避免不必要的缩写。需要重复使用的缩写，在首次出现时写出全称并说明含义；保留代码标识符和官方名称。 - 选择准确、具体且容易理解的术语。必要的专业术语附简短解释，不机械地把“prompt”改成“input”等可能改变含义的词。 - 在陌生概念前，用一句用途说明或熟悉的场景帮助读者定位。若读者只需要执行步骤，直接给操作。 - 补齐容易导致卡住的前置条件，例如依赖安装、权限、环境变量和工作目录。把可选背景放在链接或独立小节中。 - 在关键操作后说明预期结果或验证方法。对有依据的常见失败，给出症状、原因和可执行的修复方法。 - 细节以完成任务为边界。为初学者提供足够帮助，同时让熟悉主题的读者能跳过基础说明。 ## 让示例可以迁移和验证 - 使用解决问题所需的最少依赖。优先给出自包含示例，避免读者在多个章节之间拼接代码。 - 说明示例所需的输入、配置和预期输出。清楚标识需要替换的值，并区分可运行代码与伪代码。 - 示例也必须体现正确做法。例如通过适当的配置或环境变量读取密钥，不把密钥写进代码。 - 保留准确的命令、参数、类型和返回值。不要为了语言简化而改变技术语义。 - 按任务需要核对代码、项目资料或当前官方文档。不要编造 API、性能数字、验证结果或来源。 - 在环境允许且操作合适时运行关键示例。无法运行时，说明尚未验证的部分，不声称示例已通过验证。 ## 从读者角度检查结果 交付前快速检查以下问题，修正影响理解或执行的问题。无需把检查表附在每次交付中。 - 只看标题和各段首句，能否找到答案并理解主要结论？ - 从中间章节进入时，能否理解主题、必要条件和引用对象？ - 目标读者能否按说明完成任务，并判断结果是否正确？ - 术语、结构和示例是否一致？是否存在歧义、无根据的读者假设或不必要的缩写？ - 事实、命令、链接和预期结果是否可靠？是否明确区分已验证内容和待确认内容？ - 能否删除某段而不损失读者需要的信息？是否有必要信息因追求简短而缺失？ 这些原则服务于读者，不是固定模板。有充分理由时可以调整：例如参考文档保留标准标题，短说明省略目录，已有熟悉结构继续沿用。以准确、易找、易懂和可操作为判断依据。