文档写作原则 · Arkk 的笔记

帮助作者确定文档要交付什么认识或行动支持，并安排内容、结构与阅读路径。人和 Agent 共用一份权威内容，角色或操作方式的差异在相应内容处说明。

核心原则

先确定读者与目的，再选择内容与依据，最后安排组织和表达。局部问题来自上层时，先回到上层：主张没有想清，改句子不能补足判断；读者与目的不明，调整目录也难以确定取舍。

以读者需要为起点：文档体系、单篇、章节与段落分别承担具体问题，划分和顺序由这些问题决定。
按实际作用取舍：相关不等于有用；保留能服务当前目的的内容，包括必要的依据、感受与个人声音。
让主线可见、支撑完整：说明、方案与操作文档先交付核心认识或行动路径，再展开依据与做法；关键条件随主张出现。

本文负责“写什么、怎样组织”；文案与措辞负责描述角度、风格和具体表达。修改后回到阅读场景检查效果，而不只检查字句是否通顺。

先确定读者、场景与目的

把文字放回它实际出现的位置，先回答四个问题：

写给谁？ 读者已有多少背景，关心什么，与作者是什么关系？第一次到访的人需要用途说明，维护者可能更需要精确术语；私人记录还要保留作者自己的表达习惯。
希望产生什么作用？ 是让人理解、找到内容、作出选择、完成操作，还是愿意继续读、感到共鸣、记住一种观点？目的有多个时，确定当前最重要的一项。
在哪里、怎样被读到？ 搜索结果和目录常被扫读，教程会被边读边操作，随笔可以逐步展开。位置、篇幅和阅读节奏影响信息顺序与表达密度。
周围内容已经承担了什么？ 标题、作品、图片和操作也在传达信息。文字可以补充事实、说明关系、表达态度或营造氛围，具体取舍看它对当前目的的贡献。

例如，作品列表旨在让访客快速找到项目时，“这里收录了我的项目和笔记”通常可以删除。若开场希望让访客认识作者，可以讲选择这些题目的原因或一段经历；此时个人声音有作用，没必要改成工具说明。

选择内容与依据

先说清希望读者得到的主张、判断或做法，再确定支持它所需的背景、事实、条件、推导与示例。信息增量是说明和导航的重要尺度；情感、态度、氛围与记忆点也可以是文字的作用。取舍依据是当前目的，不把所有内容都改成同一种简短、客观的说明。

默认读者不熟悉当前主题，再根据已知读者调整背景与术语密度。读者只能凭文档及其引用材料理解关键推导、采取行动并判断结果；不依赖未交代的对话上下文。上层框架能够涵盖某个认识，不等于读者会自行想到，能改变实际判断的认识应明确讲出。

不同用途需要不同的支撑：

文档用途	应提供的支撑
解释或支持决定	必要概念、事实依据、推导、适用条件与取舍
指导操作	准备条件、动作、分支、完成标准与必要排障
复盘和调查	与结论有关的过程、证据与尚未解决的问题
表达经历或感受	能传达体验的场景、细节、变化与个人声音

已有可用的命令、请求、配置或输入输出时，保留最小示例，说明输入来源、需替换的位置和验证状态。较长的前置知识可通过链接提供。

将内容放回上下文，暂时删去再读：是否损失了当前目的需要的信息、感受、节奏或衔接？没有损失时可删除或合并；缺少依据时先补事实，不能靠增加句子凑完整。具体的空泛表达处理见文案与措辞。

文档体系的组织

明确分工与关系

整体问题可按对象、阶段或具体疑问划分。同一层级的划分依据应清楚，换一种划分方式时说明关系。让读者看懂哪些部分独立使用、哪些有前提、哪些提供共同依据。

例如，产品设计文档可以分别讨论目标与范围、行为规则、原型和价值验证。原型依据目标与规则，也可能暴露规则缺口；价值验证可以发生在投入前或使用后。它们的关系应在入口说明，不能让读者把目录顺序当成执行顺序。

按职责划分，保持使用完整

一份文档承担一个具体职责，所需的背景、依据、步骤与示例放在一起。常见职责包括：

文档职责	应承载的内容
解释与导航	用途、适用范围、内容关系与阅读入口
支持理解或判断	概念、原则、判断依据、推导与示例
指导一项操作	准备条件、动作、分支、完成标准与必要排障
提供可复用的表达形式	模板结构、填写说明与示例

入口负责解释自身和导航，具体方法与交付细则放在对应文档。简单主题写成一篇完整说明即可；拆分以任务为单位，让读者一次拿到一个任务所需的全部规则。

维护权威内容与阅读路径

同一规则或方法只维护一处权威内容，其他文档引用它。摘要帮助读者选择和把握主线，详细规则在原处展开。通用原则集中维护，领域文档说明具体应用与特有要求。

导航用读者能识别的问题、现象或任务引导选读，不要求读者预先知道根因。说明必要的阅读依赖；新增或调整内容时同步更新索引和引用。

单篇文档的写作

让开头先交付核心认识

说明、方案和操作文档应将最重要的答案集中放在开头。说明文先给核心认识，方案先给建议与关键取舍，操作文档先给最小可用路径。短文用一句话或一段话即可，不必统一设置“总览”标题。

叙事与抒情内容可以按事件、感受和节奏逐步展开，开头服务其阅读目的。

总览应包含可用的判断，不能只预告后面有哪些主题。例如，“本文讨论职责、内容与结构”只说明范围；“各部分围绕要解决的问题组织，不能帮助理解或行动的相关内容也应删去”才传达了原则。

总览与展开承担不同作用：总览让读者抓住结论及关键条件，展开解释为什么、如何判断和执行，并提供证据或示例。换词重述总览，或把核心结论藏进展开部分，都算总览未完成。会改变结论或行动的关键限制应随要点出现。

写完后暂时遮住后文，只读开头：能否说出最重要的判断或下一步，而不只是复述章节名？若不能，先重写总览；不要靠加粗所有段落或要求全文必读来弥补主线缺失。

按读者需要展开

先明确各节要回答的问题和相互关系，再安排顺序。让读者看清结论怎样得到依据支持、操作怎样走向完成，不让读者陪作者重走探索过程。

按阅读依赖安排内容：概念支持后续判断，依据支撑结论，步骤通向完成标准。需要独立查阅的内容保留必要上下文，较长的共同前提通过链接引用。复盘和调查可以保留支撑结论的过程，纯概念说明不必套用操作流程。

用形式表达关系

内容关系	适合的形式	使用要点
同层级、同维度的比较	表格	对齐差异，不为整齐把不同层级压成并列项
包含、分解、逐层推导	标题或嵌套列表	表达层级与从属
因果与论证	段落	保留推理过程与语气衔接
流程、状态、依赖、页面布局	图，如 Mermaid 或 HTML 渲染	从权威内容生成，不另立需要同步维护的事实

修改与检查

修改前识别原文的用途、关键事实、适用条件与推导关系。润色保留原意与要求强度，不能确认等义时先保留，纠错须有依据。收到反馈先整合已有内容，确有缺口再补，不把纠错过程逐条追加到正文。

按读者的阅读过程检查：

对照目的读开头：说明、方案与操作文档能否交付核心认识或行动路径，以及关键条件？叙事与抒情内容是否建立了需要的场景、声音或阅读期待？
再看组织：整套文档的分工与关系是否清楚？只读文档标题与各级标题，能否辨认主题、范围和内容关系？标题应具体说明对应内容。各篇、各节是否帮助解决对应问题？内容只是相关却没有作用时，应删减或重新组织。
按用途走读：导航能否选路，说明能否理解，操作能否执行并确认结果，提案能否支持决定，随笔能否传达体验与声音？需要猜测或反复拼接规则时，回到对应层面调整；重要效果需要时请目标读者反馈。
核对表达与引用：检查术语、指代、要求强度、链接与格式，确认修改没有破坏原有价值或留下冲突。

机械检查不能代替内容判断，文档走读不能代替实际执行验证。交代检查结果时说明覆盖范围和未验证部分。

常见反模式

以下保留写作中的实际纠正，格式与收录规则见反模式记录方法。

场景与条件	被否的做法	采纳的做法	决策依据
整理 practical-memory 文案及审阅界面设计方法时，用户指出主张后的补充含有防御性解释。	在主张后追加“不是……”“不构成……”或“仍需验证”等限定、例外与提醒，防备假想误读。	按防御性解释的处理方法重写规则：删去无实际作用的补充，将必要范围与条件融入正面主张，后续展开帮助理解和执行主张。	补丁式限定分散主线，逐句正确也会增加阅读负担；取舍看其对当前理解和行动的作用，必要条件随主张表达。
写方法节，内容逐句正确却被评价“没有营养”，定点改写后仍无改善。	保留与共识常识无法区分的规则表述，靠补句子加信息量。	点出规则防止的偏差，让针对性可见；删掉不改变读者行为的句子，或并入相邻内容。	真正有信息量的是针对具体偏差的默认倾向；防止的偏差没写出时，规则与常识无法区分，删掉也不改变读者行为。
新建公开仓库发布项目，沿用内部开发 README，检查只核对路径残留等机械项即认为可用，用户指出“太机械”。	直接发布开发台账（功能罗列、版本史、内部排查记录、防御性边界），以机械项通过代替读者视角检查。	发布前按目标读者重写：开头讲清是什么、为什么值得用、与替代方案的差异；删去版本史与排查记录，边界集中一节、措辞直接。	开发台账服务于 agent 协作，不是面向使用者的文档；机械项核对通过不等于可发布，检查须过读者视角。

#写作 #知识管理