本文永久链接 – https://tonybai.com/2025/07/14/writing-style-guide

大家好，我是Tony Bai。

作为一名开发者、架构师或运维专家，我们大部分时间都在与代码、系统和架构打交道。然而，我们同样在持续不断地进行另一种形式的“编码”——沟通编码。无论是撰写一个清晰的 README.md，提交一份详尽的 Pull Request 描述，编写项目内部的技术文档，还是在社区中回答一个问题，我们都在扮演着“技术作者”的角色。

代码的质量决定了软件能否运行，而沟通的质量则决定了项目能否高效协作、知识能否有效传承、社区能否健康发展。一份糟糕的文档，如同晦涩难懂的“面条代码”，会极大地消耗团队的精力和热情。

最近，Redhat公司发布了《Red Hat Technical Writing Style Guide》7.1版本。这份指南不仅仅是一系列规则的集合，它更像是一部由顶级开源软件公司沉淀下来的、关于如何通过清晰沟通来提升工程效率的哲学。

在这篇文章中，我将提炼其中的一些精髓，探讨那些能直接提升您和团队工程能力的写作原则，供大家参考。

写作的“第一性原理”：清晰、精确、用户至上

技术文档的首要目标是传递信息，任何模糊、冗长或模棱两可的表达都是工程效率的天敌。指南强调了几个核心原则：

1. 拥抱主动语态，指令明确无误

主动语态让指令更直接、更有力。在指导性文档中，这能显著降低读者的认知负荷。

对开发者的价值：当用户（或未来的你）阅读操作手册时，清晰的指令意味着更低的出错率和更快的解决问题速度。

2. 杜绝冗余，尊重读者的时间

避免使用不必要的填充词，让每一句话都言之有物。

3. 避免歧义：This 指的是什么？

在技术文档中，代词（如 this, that, it）是歧义的重灾区，尤其对于翻译和非母语阅读者。指南建议明确指出代词所指代的的名词。

- A site can use these to self-assign a private routable IP address space.
+ A site can use these unique local addresses to self-assign a private routable IP address space.

- This causes SSH to lose the recorded identities.
+ This action causes SSH to lose the recorded identities.

对开发者的价值：在复杂的配置说明或问题排查指南中，消除代词歧义可以防止因误解而导致的配置错误。

为全球化社区而写：包容性与可翻译性

开源项目和现代技术团队本质上是全球化的。我们的文档需要被不同文化背景的人阅读和翻译。

1. 使用包容性语言

这是现代技术社区的基石。避免使用可能带有偏见或冒犯性的术语，有助于建立一个更健康、更多元化的社区环境。

• master/slave -> 推荐使用 primary/replica, controller/worker, leader/follower 等。
• whitelist/blacklist -> 推荐使用 allowlist/denylist 或 blocklist。
• 性别代词 -> 避免使用 he/she，推荐使用中性的 they（可指代单数）或直接使用第二人称 you。

2. 为翻译而设计

糟糕的措辞会给机器翻译和人工翻译带来灾难。一些简单的规则可以极大地提升文档的可翻译性：

• 避免使用俚语和行话：eat your own dogfood (使用自己的产品), boil the ocean (范围过大) 等表达在其他文化中可能完全无法理解。
• 慎用 may 和 should：may 可能表示“可能性”或“许可”，should 可能表示“建议”或“期望”。使用 can (可以), might (可能), must (必须) 会更精确。
• 避免名词堆叠：Standard system log management configuration 这种连续名词的组合，在翻译时极易出错。可以调整为 Standard configuration of system log management。

工程师的文字“代码规范”：一致性与标准化

如同 eslint 或 gofmt 为代码提供规范一样，风格指南为我们的文字提供了“格式化”标准。这能确保整个项目文档风格统一，易于阅读和维护。

1. 统一命令语法文档

在展示命令行示例时，保持一致的格式至关重要。

# 一个清晰的命令语法示例
$ git clone [username@]hostname:/repository_filename [directory]

- 使用 $ 表示普通用户，# 表示 root 用户。
- 使用 [] 表示可选参数。
- 使用斜体或描述性词语（如 _filename_）表示 需替换的值。
- 在需要省略输出时，使用 ...output omitted... 标记，而不是随意删减。

2. 精确描述 UI 元素

当描述用户界面时，精确和简洁是关键。

• 直接了当：不说 Click the Save button，而说 Click Save。
• 名称匹配：文档中的 UI 元素名称（如按钮、菜单项）应与界面上显示的完全一致（包括大小写）。
• 导航路径：使用 -> 或 →清晰地表示导航路径，例如：Go to Monitoring → Metrics。

3. 避免产品名称的所有格

一个看似微小但能提升专业度的细节：

• 不推荐: Red Hat OpenShift’s Logging operator creates…
• 推荐: The Red Hat OpenShift Logging operator creates…

总结与展望：将沟通视为工程技艺

《红帽风格指南》带给我们的最大启示是：清晰、精确、专业的书面沟通不是一种“软技能”，而是工程技艺（Craftsmanship）不可或缺的一部分。它与编写高质量代码、设计健壮架构同等重要。

下一次，当你准备提交一个 Pull Request、更新一份 README，或撰写一篇技术博客时，不妨尝试运用其中的一两个原则：

• 将一个被动语态的句子改为主动语态。
• 检查是否有模糊的代词 it 或 this 可以被替换。
• 思考一下你使用的术语是否足够包容和全球通用。

投资于沟通，就是投资于整个团队的效率和项目的未来。正如一份优雅的代码令人赏心悦悦目，一份清晰的文档同样能带来极致的工程之美。

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。

本文永久链接 – https://tonybai.com/2025/07/12/insanely-productive-in-go

大家好，我是Tony Bai。

在软件开发的世界里，我们总被灌输一种观念：选项越多，工具越强，生产力就越高。于是，我们追求功能最全的框架、最灵活的配置、以及最新潮的库。

但最近，在 Reddit 的 r/golang 社区，一篇名为《我感觉用 Go 的效率高得离谱》(I feel insanely productive in Go) 的帖子引发了近百条热议。一位曾坚信 TypeScript 和 Python 是“快语言”的开发者，在亲手尝试 Go 之后，发出了“真香”的感叹。

他发现，之前在 Node.js 生态中，光是技术选型——选择哪个运行时 (Bun? Deno?)、哪个 Web 框架 (Express? Fastify?)、哪个 ORM (Prisma? Drizzle?)——就足以耗费他整整一周的时间。他称之为“分析瘫痪” (Analysis Paralysis)。

而在 Go 中，他一天之内就搭建起了项目，开始编写业务逻辑。

这个故事并非孤例，它触动了无数从其他语言生态“迁徙”而来的开发者的心弦。它揭示了 Go 语言一个常常被误解，却又极其强大的超能力：正是那些看似“无聊”的、更少的选项，才赋予了我们惊人的生产力。

告别“分析瘫痪”：Go 的“默认路径”之力

为什么选项更少反而更快？因为 Go 的设计哲学从一开始就在极力避免“分析瘫痪”，为开发者提供一条清晰、低阻力的“默认路径”。

1. 强大的标准库：你的第一选择，也是最好的选择

Reddit 上的高赞评论一针见血：“在 Go 中，你不需要从一个框架开始，标准库已经提供了你需要的大部分东西。”

想写一个 Web 服务？net/http 就是你的起点。想操作数据库？database/sql 就在那里。想处理 JSON？encoding/json 已为你备好。

这些标准库不仅功能强大、性能卓越，更重要的是，它们是 Go 团队维护的、最稳定、最符合 Go 哲学的实现。这意味着，当你遇到问题时，你面对的是整个 Go 社区的集体智慧，而不是某个特定框架的小圈子。

2. “小工具”生态：组合优于继承

当然，标准库并非万能。但当你需要第三方库时，你会发现 Go 的生态也与众不同。这里没有像 Java Spring 或 JavaScript React 那样“统治一切”的庞大框架)。

取而代之的，是一个由无数“小而美”的、可组合的库构成的生态系统。比如，你需要一个更强大的路由？chi 或 gorilla/mux 可以无缝地与标准库的 http.Handler 配合。你需要一个配置库？Viper 可以专注于做好这一件事。

这种模式的好处是显而易见的：你只引入你需要的，你的项目不会被一个臃肿的、你只用了 10% 功能的框架所绑架。

“语言开发者” vs. “框架开发者”：Go 的纯粹之路

这种生态哲学，引出了一个更深层次的问题：你到底是一个“语言开发者”，还是一个“框架开发者”？

在许多其他生态中，框架的存在感甚至超过了语言本身。
* 一个 Java 工程师的简历上，写着“精通 Spring Boot”，这比“精通 Java”本身可能更具分量。
* 一个前端工程师，很可能对 React 的生命周期了如指掌，却对 JavaScript 的原生事件循环感到陌生。

这是因为，那些庞大的框架往往会重新定义语言的工作方式，引入大量“黑魔法”般的抽象和依赖注入。你写的是框架的 API，遵循的是框架的范式。你的技能，与这个框架深度绑定。一旦需要更换框架，或者脱离框架工作，你可能会发现自己几乎要重新学习一门“新语言”。

而 Go 社区，自始至终都在走一条“纯粹之路”。

这里的目标，永远是成为一个更好的 Go 开发者。因为标准库的强大和生态的“小工具”特性，无论你在哪个公司、哪个项目，你所依赖的核心思维和工具集都是一致的。你学到的 context 包的用法、interface 的设计模式、goroutine 的并发模型，这些知识具有极高的可移植性。

你不是在学习一个框架的“方言”，而是在掌握一门通用语言的“普通话”。这不仅提升了你个人的职业安全感，也极大地保障了项目的长期可维护性。

小结：在“约束”中寻找自由与效率

Go 的生产力优势，根植于其看似“固执”和“无聊”的约束之中。

它通过一个强大的标准库和一套约定俗成的惯例，为你铺设了一条清晰的道路，让你免于在无穷无尽的选择中耗尽心力。

它通过一个由小工具组成的、可组合的生态，让你专注于学习语言本身，而不是被某个庞大的框架所束缚，从而保护了你最宝贵的资产——你的知识和技能。

最终，Go 通过减少不必要的外部认知负荷，将你最宝贵的资源——注意力——解放出来，让你能真正地聚焦于业务逻辑，聚焦于创造价值。

这或许就是为什么，那么多开发者在体验过 Go 的“少即是多”之后，再也回不去了。因为他们发现，真正的自由与效率，恰恰来自于“恰到-好处”的约束。

资料链接：https://www.reddit.com/r/golang/comments/1lx52vz/insanely_productive_in_go_rethinking_everything/

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。