readable-docs

易读文档

目标

让项目技术记录便于浏览和使用：事实优先，其次是易查找、简洁和自然表达。用尽可能少的文字保留原意：默认使用短语，必要时使用完整句子，只有在有助于说明关系时才使用段落。写得像实用的幻灯片备注，而不是论文或口号集。

撰写原文时就采用这种风格，而不只是收到润色要求时才采用。它与当前任务或记忆技能配合使用；不会额外生成报告、增加审批步骤或创建文档。

1. 理解原意

• 阅读相关来源及其上下文。确认读者需要了解、决定或执行什么。
• 编辑时，严格限定在请求范围内。不要批量改写归档内容、引用的证据或无关文档。
• 保留事实及其关系：参与者、动作、原因、条件、例外、否定、选项和不确定性。不要把观察结果变成规则，也不要把提议说成决定。
• 保留准确的技术名称、路径、命令、配置键、版本、日期、数字、单位和来源引用。切勿编造具体细节、经验、观点或证据，让文本显得更有人情味。
• 保留必需的章节、输出路径、状态字段和指令强度。把“必须”缩短为“可以”会改变行为，而不只是编辑文案。

2. 便于浏览的结构

先写有用的结论、状态或后续操作。使用能说明读者可以查到什么的标题；避免使用“综合分析”这类空泛标题，改用“失败后如何恢复”这类能点明具体内容的标题。

内容	默认形式
独立事实、约束、发现	项目符号；每项一个要点，例如：对象：结论／条件
步骤、优先级、时间顺序	编号列表；按顺序列出简短操作
共享维度上的选项或变更	对比表；每行一个维度，各单元格简述差异
参数、状态、证据	使用便于查找的精简表格（列有助于检索时）
因果链、机制、推导	仅当短语或列表会模糊关系时，才使用简短段落
命令、配置、原样错误信息	代码块；在代码块外说明

• 不需要列表或表格时，使用简单短语或句子。
• 表格用于查找或对比，不要把段落塞进表格。将较长的理由移到表格下方或相关小节中；重要条件应紧邻其所限定的结论。
• 如果列表项包含多个独立要点，就拆分。如果需要深层嵌套，就按具体标题重新分组。将限定条件与其限定的要点放在一起。
• 避免空标题、重复的引言和结论，以及用多种格式重复相同信息。简短概述可以指向必要的详细内容，而不必重复说明。

3. 写短语，不写填充内容

使用用户的语言，默认使用中文。稳定使用已确立的技术术语，不要来回更换同义词。

• 优先使用短语和简短分句。标题或上下文已明确的主语或宾语可省略；若可能指代多个参与者，则明确指出。无需强求每条项目符号或每个单元格都写成完整句子或加句末标点。
• 将区别点前置：“仅首次安装询问”，不要写“需要说明的是，在首次安装的情况下，系统会进行询问”。
• 直接说明操作和效果：“保留本机值”，不要写“通过相应机制实现对本机值的有效保留”。
• 删除空洞的铺垫、赞美和缺乏依据的重要性表述：“下面将详细介绍”“值得注意的是”“显著提升”“奠定坚实基础”。这些是编辑信号，并非禁用词；保留承载实际含义的措辞。
• 用来源已有的事实替换含糊的说法。若缺乏依据，就说明这一点或省略说法；不要编造数字或用户评价。
• 偶尔可在相邻位置添加 PS: 补充次要理由。必要的注意事项、例外情况和故障处理应放在正文中，而非旁注。
• 谨慎使用强调。不要为每个项目符号标签加粗、到处添加装饰图标、强行凑成三点、机械地交替句子长度，也不要强设字数配额。
• 不要添加虚假的个性、第一人称感受、故意的错误或口语填充语。不要机械地禁止被动语态、标点、列表或普通的中文排比句式。

在调整风格时，或不确定缩短后是否会丢失含义时，请阅读 references/examples.md。示例仅供参考，并非必须遵循的文档模板。

4. 检查含义和呈现

返回或保存文本前：

• 对照来源检查：事实、条件、范围、不确定性和规范要求的力度是否一致？是否添加了新主张、遗漏了限定条件或调换了参与者？
• 只扫读标题、项目符号的首词和表格标题：读者能否找到结论、差异和操作？
• 阅读最长的项目符号和表格单元格：是否只表达一个要点，且在保留含义的前提下尽可能精简？拆分彼此独立的要点；添加项目符号标记或把内容挤在一行，并不能让段落变得简洁。
• 保持原始引文、代码、配置和机器可读结构不变。在 StrictDoc 中，编辑文字字段时，不要仅为调整风格而更改 UID、语法、关系、状态或分隔符。
• 使用文档现有的格式检查工具。修改 .sdoc 或 StrictDoc 配置后，从文档根目录运行 strictdoc export .，并检查相关导出内容。导出成功只能证明语法正确，不能证明文字质量。

交付所请求的文本或文件修改，不要附上写作评分表，也不要主动逐条解释所有编辑。若来源存在影响可靠改写的信息缺口，请简要指出。