• 文档

docguide/philosophy.md 是 Google 开源风格指南仓库（styleguide）中docguide/文档指南子项目的哲学基石，它为「如何编写工程文档」确立了四条核心原则：激进简化（Radical simplicity）、可读源文本（Readable source text）、最小可行文档（Minimum viable documentation）与更好胜过完美（Better is better than perfect）。本文以这份哲学文档为骨架，结合 docguide/best_practices.md、docguide/style.md 与 docguide/READMEs.md 等配套文档，系统讲解这套理念的每一个主张、背后的动机，以及如何在 Markdown 写作与 README 维护中落地。读完你将掌握一套可直接复用的文档写作决策框架：什么时候该删内容、为什么纯文本优于富文本、怎样让文档像测试一样被团队认真对待。

哲学文档在仓库中的位置

styleguide仓库汇集了 Google 多个开源项目的风格指南（C++、Python、Java、Go、JavaScript 等），而docguide/子目录专门回答另一个问题：这些指南以及任何工程文档本身，应当如何被撰写与维护。它由四份相互关联的文档组成（见 docguide/README.md）：

• docguide/philosophy.md：指导思想与价值观（本文主体）；
• docguide/style.md：Markdown 语法层面的具体风格规则；
• docguide/best_practices.md：文档维护的实操最佳实践；
• docguide/READMEs.md：针对 README.md 的专门指南。

四者关系是「理念 → 规则 → 实践」的递进：哲学文档定基调，风格文档约束每一条 Markdown 写法的取舍，最佳实践给出日常维护动作，READMEs 指南则把理念落到最常见的文档类型上。哲学文档以老子的「埏埴以為器，當其無，有器之用」开篇——黏土经匠人之手成为陶器，真正有用的却是器皿中空的部分（Clay becomes pottery through craft, but it's the emptiness that makes a pot useful）。这一比喻直指全文核心：文档的骨架与排版只是容器，为读者腾出的「空」——即清晰的思路与最少的干扰——才是价值所在。

原则一：Radical simplicity —— 激进简化

哲学文档将「激进简化」列为第一原则，并给出五个相互支撑的主张：

1. 可扩展性与互操作性优先于功能堆砌。规模（scalability）来自简单、速度与易用；互操作性（interoperability）来自不加修饰、易于消化的内容。与其为一个文档堆满花哨特性，不如让它在任何规模下都能快速被阅读和复用。
2. 更少的干扰带来更好的写作与更高效的阅读。每多一个装饰元素、多一段无关内容，都是在向读者征收认知税。
3. 新特性绝不应干扰最简单的用例，并且对不需要它们的用户保持不可见。这与工程中「默认路径要极简、高级能力按需启用」的设计哲学一致。
4. 这套指南为普通工程师设计——那些忙碌、只想尽快回去写代码的工程师。大型复杂文档是被允许的（possible），但不是主要目标（not the primary focus）。
5. 最小化上下文切换让人更快乐：工程师应当能用他们读写代码时所用的同一套工具（编辑器、命令行、纯文本查看）来阅读文档，而不是被迫切换进某种专用环境。

简化的目标不是「内容变少」，而是把注意力留给真正重要的信息。在仓库里，这一原则直接约束了配套风格指南的篇幅取舍——docguide/style.md 开篇就声明，Markdown 语法的选择要平衡三个目标：源文本可读且可移植、语料库可长期维护、语法简单易记。这正是「简化」在语法层面的投影：能少记的规则就不多记，能少写的标记就不多写。

原则二：Readable source text —— 可读的源文本

这一原则回答「用什么格式写文档」的问题，主张同样鲜明：

• 纯文本不仅够用，而且更优（Plain text not only suffices, it is superior）。Markdown 本身并非该公式的必要条件，但它是当下最好、支持最广泛的选择；HTML 通常不被鼓励。
• 内容与呈现不得混为一体（Content and presentation should not mingle）。任何时候都应能抛开渲染器，直接从源文件读取核心信息；不想接触呈现层的用户永远不必接触它。
• 可移植性与面向未来：尽可能保持源文件对人类可读，为「无法预想的未来集成」留出空间——任何能解析纯文本的工具，未来都可能成为文档的消费者。
• 静态优于动态，但新鲜优于陈旧：内容不应依赖任何特定服务器的功能（因此静态内容更可靠），同时文档必须持续更新（因此保持新鲜同样重要）。两者需要权衡，而非二选一。

把这条原则映射到 docguide/style.md 的具体规则上，可以看到大量一脉相承的约束：

值得注意的是，docguide/style.md 在结尾再次回指哲学文档：Every bit of HTML hacking reduces the readability and portability of our Markdown corpus——每一处 HTML 修补都在侵蚀 Markdown 语料库的可读性与可移植性，进而限制与其他工具集成的价值。这正是「可读源文本」原则被反复执行的原因：源文件本身才是长期资产，渲染效果只是短期便利。

原则三：Minimum viable documentation —— 最小可行文档

「最小可行文档」是哲学文档对「写多少」的回答，它把文档与测试并列：

• 文档在「像测试一样被对待」时才会繁荣：这原本是件必须做的杂务，但一旦体会到它的长期回报，就会逐渐爱上它。哲学文档在此直接指向 docguide/best_practices.md。
• 简短实用胜过冗长详尽：绝大多数用户只需要作者全部知识中很小的一部分，但他们需要的是「快速且经常」地拿到它。

「像测试一样对待文档」在 docguide/best_practices.md 中被展开为一套可操作的日常纪律：

文档像盆景，要经常修剪。一小撮新鲜而准确的文档，好过一大片处于各种荒废状态的松散「文档堆」。写作时要砍掉一切不必要的内容，同时养成持续打磨的习惯——Docs work best when they are alive but frequently trimmed, like a bonsai tree。工程团队应像维护测试那样用心维护文档：先识别真正需要的东西（发布文档、API 文档、测试规范），再小批量、频繁地删除冗余。

文档与代码在同一 CL 中更新。代码变更的同时必须改文档，这既能保持文档新鲜，也是向评审者解释改动意图的好机会。一个合格的评审者至少应当坚持：docstring、头文件、README.md 以及任何其他文档随 CL 一起更新。

删除死文档。死文档是坏的：它们误导人、拖慢进度、让工程师绝望、让团队负责人懒惰，还会为「在代码库里留烂摊子」开先例。清理要点包括：

• 慢慢来，文档健康是逐步积累的结果；
• 先删掉你确定是错的，拿不准的暂时搁置；
• 让整个团队参与，花时间快速扫描每份文档并做简单决定：保留还是删除；
• 迁移时默认删除或留下，落单的文档随时可以找回；
• 反复迭代。

好的胜过完美的（Prefer the good over the perfect）。文档评审的标准不同于代码评审：评审者可以也应该要求改进，但作者通常有权援引「好于完美原则」，让能改善文档的修改尽快提交，而不是反复评审到「完美」。文档永远不会完美，它会在团队逐渐明白真正需要记录什么的过程中持续变好。

文档是代码的故事（Documentation is the story of your code）。写好代码并不止于编译通过或 100% 测试覆盖——写出计算机能理解的东西容易，写出人和计算机都能理解的东西很难。Code Health 意识强的工程师应当先为人写作，再为计算机写作。这引出了一条完整的文档谱系（spectrum）：

1. 内联注释（inline comments）：主要职责是提供代码本身无法承载的信息，例如「这行代码为什么在这里」。
2. 方法与类注释（method and class comments）：
   • 方法 API 文档（header / Javadoc / docstring）：说明方法做什么、怎么用，是代码必须如何行为的契约，面向未来会使用和修改代码的程序员。它应说明参数、返回值、坑与限制、可能抛出的异常或返回的错误；「为什么」的解释通常留给内联注释。写作时想得实际一点：「这是一把锤子，你用它来敲钉子。」
   • 类 / 模块 API 文档：概述类或文件做什么，并给几个简短用法示例；存在多种用法（有的高级、有的简单）时示例尤其重要，且务必先列最简单的用例。
3. README.md：为目录里的新读者提供方向，并指向更详细的说明与用户指南：这个目录打算放什么？开发人员应该先看哪些文件，其中有没有 API？谁维护这个目录、去哪里了解更多？（对应 docguide/READMEs.md 的详细规范）

这套谱系说明「最小可行」不等于「少写」，而是按读者需要分层供给：能放进注释的一句话，就不必写成长篇散文；需要长期指引的内容，才升级到 README 与用户指南。

原则四：Better is better than perfect —— 更好胜过完美

最后一条原则管理的是协作节奏与心理状态：

• 渐进改进好过旷日持久的争论（Incremental improvement is better than prolonged debate）。对不完美的耐心与容忍，让项目得以有机演化——文档先可用，再在持续迭代中变好，而不是在讨论中原地打转。
• 不要舔饼干，传递盘子（Don't lick the cookie, pass the plate）。我们正被海量潜在项目淹没；只选择你真正能handle的那些，把你无法handle的释放出去。这是对个人精力与注意力的清醒管理：与其低质量地攥住所有文档，不如高质量地维护少数几份，并把其余交给更合适的维护者。

这一条与前三条形成闭环：简化降低起步门槛，可读源文本降低维护成本，最小可行降低写作负担，而「更好胜过完美」保证这一切可以在团队协作中长期运转——没有人会因害怕达不到完美而停止改进，也没有团队会因追求完美而陷入停滞。

从哲学到实践：一套可落地的文档决策清单

把 philosophy.md 的四条原则与配套文档整合，可以得到一份可直接用于日常工作的核对清单：

动笔之前（Radical simplicity + Minimum viable documentation）

• 这篇文档的核心读者是谁？他们此刻最需要的一个信息是什么？
• 这个信息用一段注释、一段 docstring 还是 README 承载？按 docguide/best_practices.md 的谱系选择层级，不要越级写作。
• 哪些内容属于「作者的全部知识」但读者用不上？砍掉。
• 新加的章节、示例、链接是否会让最简单的阅读路径变复杂？若是，移到附录或拆分。

写作之中（Readable source text）

• 只写标准 Markdown，不混入 HTML（除非是必须的大表格）；代码块用围栏并声明语言；用反引号包裹会被自动链接误伤的伪路径（docguide/style.md）。
• 保持 80 字符行宽，链接、表格、标题、代码块可以例外。
• 标题用 ATX 风格，全文只用一个 H1，子标题名称完整且唯一（便于自动生成直观的锚点）。
• 行内链接使用显式路径；同一目录内才用相对路径，避免../式相对链接；长链接用引用式链接并在首次使用后就近定义（docguide/style.md）。
• 检查源文件：不依赖渲染器，光读源码能否看懂全文？

提交之后（Better is better than perfect + 维护纪律）

• 文档是否与代码在同一 CL 中提交？是否在 CL 描述中向评审者说明了改动意图？
• 是否定期做「保留还是删除」的扫描，小批量删除死文档？
• 是否允许「好的但不是完美的」版本先合入，再逐步迭代？

写 README 时（docguide/READMEs.md）

• 文件名必须是README.md（Gitiles 不展示名为README的文件）；
• 至少覆盖四要素：这个包/库是什么、用来干什么；联系谁；状态（是否弃用、是否面向公开发布）；更多信息去哪找（如 overview.md、API 文档）；
• 记住它是目录的落地页，是多数读者遇到的第一份文件，要给出方向而非倾泻全部细节。

小结

docguide/philosophy.md 用四句短小、决断的主张勾勒出 Google 文档写作的世界观：简化到只留下真正有用的部分（激进简化）；把内容与呈现分离、让源文件本身可读（可读源文本）；把文档当作需要持续修剪的测试来维护（最小可行文档）；接受不完美、用渐进改进推动协作（更好胜过完美）。它把「器」的比喻贯彻到底——风格指南、Markdown 语法、README 模板都只是黏土塑成的容器，真正创造价值的，是容器中为读者留出的「空」。这套哲学并不追求文档的数量与篇幅，而是追求信息以最低成本抵达需要它的人。

在 styleguide 仓库中继续深入：若想了解语法层面的完整规则，阅读 docguide/style.md；想获得文档维护的操作细则，阅读 docguide/best_practices.md；想掌握 README 的写法，阅读 docguide/READMEs.md；各语言风格指南的入口与索引见根目录 README.md。

• 文档