effective-document-writing

name	effective-document-writing
version	2.3.2.0
description	起草、重构或评审面向交付的技术文档、设计文档、方案、报告、说明和 Markdown。用于解决主线不清、黑话或空话过多、内容重复、细节淹没重点、术语混乱，以及把对话和修改过程带入正式文档等问题；不替代特定文件格式的排版工具。

Effective Document Writing

把文档当作帮助读者理解、判断和行动的接口，而不是对话、探索过程或知识素材的堆放处。

确定写作任务

写作前明确三件事：目标读者已经知道什么，读完需要判断或执行什么，哪些事实、依据、约束和风险会影响该行动。无法服务这些目标的内容不进入正文。

文档类型决定内容边界：设计文档写结论、依据和取舍；规范写可执行规则；报告写发现、影响和行动；操作指南写前置条件、步骤、验证与回退。不要把一种文档写成另一种文档。

重构已有文档时，先识别权威输入及其优先级；原稿是待审材料，不因已经写入就自动成为事实。低优先级原稿中的独有说法，即使未被权威输入否定，也不等于获得支持；无依据的细节应删除或标为待确认，不能自行补全。用户指定的修改是全文约束，应同步到定义、正文、表格、图和验证项，而不是只改被点名的段落。

组织主线

优先按读者理解顺序组织：结论或目标、关键依据、影响与边界、行动或验证。结构随内容调整，不为满足形式机械填充章节。

• 标题表达认知层级，不装饰版面。
• 表格用于稳定映射和比较，列表用于并列规则，图用于关系、顺序或状态。
• 正文承载所有目标读者都需要的主线；原始证据、完整参数和低频细节移入引用或附录。
• 同一事实只在权威位置完整表达一次，其他位置引用或补充新信息。

控制语言和信息密度

每段至少提供一项新内容：事实、结论、关键原因、约束、风险或行动。删除后不影响理解、判断和执行的段落应删除或合并。

• 优先使用行业通用词和具体对象，避免用抽象名词包装简单事实。
• 必要术语首次出现时定义一次；同一概念保持同一名称。
• 不使用“赋能、抓手、闭环、拉通、沉淀、对齐颗粒度”等词替代可直接说明的动作、对象和结果；行业内确有精确定义时除外。
• 避免“显著提升、全面保障、充分考虑、持续优化”等没有对象、条件或验证方式的表态。
• 重要结论提前，不用重复和大段加粗制造重点。
• 复杂内容可以详细，但实现细节、背景知识和例子不能淹没决策主线。

隔离对话和修改过程

正式正文应脱离对话和编辑过程独立成立，只保留当前有效的事实、规则、决策，以及文档目的所需的迁移和兼容关系。

例如，应排除：

• 依赖前置对话才能理解的内容，如“根据你的要求”“如前所述”“经过讨论”；
• 与文档目的无关的生成过程，如 Agent、生成轮次、提示词或工具试跑记录；
• 不影响最终结论的探索过程，如被推翻的方案、排查轨迹和作者心理活动。

保持准确和可评审

• 区分事实、判断和待确认项；没有依据时不把推测写成结论。
• 关键结论提供足以复核的依据，但不把完整取证过程复制进正文。
• 写清适用范围、前提、失败条件和不包含内容，避免绝对化承诺。
• 细节精确到支持当前读者行动即可；不要用伪代码、字段大全或逐行解释替代设计和说明。

交付前检查

• 读者能否快速找到结论、风险和下一步？
• 每段是否提供新的认知或行动价值？
• 是否存在黑话、空泛表态、同义重复或不必要的新术语？
• 主线是否被背景、证据或实现细节遮蔽？
• 是否混入对话、修改历史、试错过程或 AI 生成痕迹？
• 同一事实是否只有一个权威定义，术语和结论是否前后一致？
• 原稿中的结论是否有权威输入支撑，指定修改是否已贯穿所有相关位置？
• 读者能否依据文档完成预期判断或行动？

发现问题时优先删除、合并、重排和具体化，不通过追加解释掩盖结构问题。