readme-writer

可读性与 README 写作

两项任务。常见的一项：衡量并提升任何文本的阅读难度—— 文档、邮件、提案、规范或计划。更具体的一项：规划 README 的结构。

始终测量，切勿估算

在整篇文档中，无法准确地凭感觉计算音节数。报告 Flesch-Kincaid 分数却不运行脚本，就是在猜。运行脚本。

cat FILE | ruby scripts/flesch_kincaid.rb

它适用于任何文本，不只是 Markdown——可以通过管道输入邮件草稿、文档中的一节，或粘贴到 heredoc 中的段落。

目标：年级水平为 11 或以下。 技术术语会拉高分数，这没关系——目标是让周围的文字清晰易懂，让技术内容更容易理解。

修改后重新测量。修改时重点关注：

• 缩短句子（而不是简化术语）
• 将复杂的连接词换成简单的连接词
• 将包含多个从句的句子拆成两句

报告修改前后的分数。

词汇覆盖率

许多技术文档读者的母语并非英语。

cat FILE | ruby scripts/vocabulary_profiler.rb

尽量提高最常见的 1000 个英语单词在文中的占比。技术术语会拉低这个比例，这是预期之内的。让非技术词汇保持简单。

建议：

• 使用主动语态
• 保持名词短语简短直接
• 将嵌套从句限制在一层
• 使用简单的“如果/那么”条件句
• 使用过渡词明确表达逻辑关系（however、therefore、because）
• 必要时将信息分散到多个句子中

避免：

• 在名词前堆叠多个修饰语（“最近修订的标准化测试协议”）
• 使用混合或倒装条件句（“Had she known...”）
• 期待读者自行推断观点之间的关系
• 在一个句子中塞入太多新概念
• 假设读者熟悉习语或文化典故

行文流畅与过渡

• 先介绍概念，再讲细节。先让读者了解“为什么”，再说明“怎么做”
• 在主要章节之间添加过渡，让文章读起来像连贯的叙述，而不是互不相关的内容块
• 按照从概括到详细的逻辑顺序展开

README 结构

如果文档是专门的 README，应按以下章节展开：

1. 是什么以及为什么 — 说明软件包的功能及其重要性（“这对我有什么好处”）
2. 安装与使用 — 说明如何快速上手
3. 配置 — 介绍常见选项和方法
4. 贡献 — 说明如何参与贡献，或指向 CONTRIBUTING.md。介绍构建环境和可移植性
5. 项目结构 — 介绍不常见的顶层目录或文件，并提示如何浏览源代码

格式

使用 GitHub 风格的提示块突出重要信息：

注意

[!IMPORTANT] [!NOTE] [!TIP] [!WARNING]

• 首次介绍关键概念时使用粗体
• 命令、文件名、配置键和值使用 code
• 示例使用具体且有描述性的名称（如“发票审批”，而不是“示例 1”）

质量检查清单

• Flesch-Kincaid 年级水平已通过脚本测量，且不高于 11
• 已测量词汇覆盖率；非技术词汇保持简单
• 各章节之间衔接自然
• 首次出现关键概念时使用粗体
• 示例使用真实场景名称，而非通用占位符
• 不使用企业套话（comprehensive、robust、seamless、leverage、utilize）
• 全文术语一致（同一概念使用同一个词）
• 首次出现缩略词和专业术语时给出定义
• 尽可能使用主动语态

参考资料

• GNU 编码标准，https://www.gnu.org/prep/standards/html_node/Releases.html
• 软件发布实践 HOWTO，https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html