本文永久链接 – https://tonybai.com/2025/08/25/documents-the-architects-programming-language

大家好，我是Tony Bai。

从初级到高级，开发者的职业路径通常是清晰的：写出更好的代码。但当站在高级工程师的十字路口，是转向管理还是深入技术成为架构师？许多人选择了后者，却发现这个角色的定义模糊不清。最近，stackoverflow的一篇精彩的博客文章《文档：架构师的编程语言》提出了一个深刻的洞见：高级开发者将代码部署到代码构成的系统中，而架构师将想法部署到人构成的系统中。

本文将和大家一起来学习一下文章中的观点和方法，并探讨为何高效的文档写作，是工程师实现这一关键角色转变的核心技能。

架构师之路：一个定义模糊的岔路口

对于许多热爱技术的资深工程师来说，放弃编码转向管理岗是一个艰难的抉择。架构师（Architect）或首席工程师（Principal Engineer）的职业路径，似乎提供了一个两全其美的方案：既能继续深入技术，又能扩大个人影响力。

然而，架构师的角色究竟与高级开发者有何不同？毕竟，他们看起来都在做相似的事情：写代码、审查 PR、讨论部署流水线。文章作者一针见血地指出了核心区别：

• 高级开发者知道如何将代码部署到由代码构成的系统中。
• 架构师知道如何将想法部署到由人构成的系统中。

这并非一句空洞的比喻。它意味着架构师的核心工作，是超越单纯的代码实现，去解决那些真正阻碍项目前进的、更大的“人的问题”：沟通、说服和决策。

文档：部署“想法”的“基础设施即代码”

在软件世界里，我们无法仅仅通过一次 git push 就启动一个跨越数月的大型项目、重写一个核心服务，或者为一个新产品选定技术栈。这些重大决策需要跨团队、跨职能的协作、输入和共识。

那么，我们如何可靠地、可重复地将一个复杂的“技术想法”部署到由不同观点、不同背景的人组成的组织中呢？作者给出的答案是：文档。

Confluence, Google Docs, Notion… 这些工具就是架构师的“部署平台”。一篇精心撰写的文档，是推动想法落地最有效的“传输协议”和“基础设施即代码”。它能：

1. 异步地将你的想法传递给所有利益相关者。
2. 结构化地呈现问题背景、方案和权衡。
3. 持久化地记录决策过程，供未来追溯。
4. 最高效地利用关键人物（通常是最忙碌的人）的碎片化时间。

优秀技术文档的原则与技巧

许多程序员对写作感到畏惧，认为其主观且难以掌握。但文章指出，编写优秀的技术文档并不需要文学天赋，只需要掌握几个简单的技巧。

技术文档宣言

作者提出了一个类似“敏捷宣言”的文档价值观：

• 随时记下东西 胜过 担心如何组织它们
• 文档化的文化 胜过 走过场的行为
• 思考什么才重要 胜过 使用模板
• 某个时间点的文档 胜过 持续更新

核心思想是：先写下来，再求完美。 与其纠结于完美的格式，不如先把你知道的记录下来。

两个魔法技巧：要点和标题

1. 要点 (Bullet Points)：这是架构师最好的朋友。它强迫你以结构化、信息密集的方式思考，而不是追求华丽的辞藻。对于读者而言，要点易于快速扫描，能在最短时间内获取核心信息。
2. 标题 (Headers)：使用有意义的标题来组织你的要点，就像在编程中将一个大函数重构成多个小函数一样。一个清晰的“上下文（Context）”标题，能迅速帮助读者（包括未来的你）回忆起项目的背景和约束。

文档的生命周期：一次性的“脚本”，而非“活服务”

成为架构师的一个重要的心态转变是：将大多数文档视为一次性的 Bash 脚本，而不是需要持续维护的 SaaS 应用。 这点与笔者近几年的实践不谋而合。

一篇设计文档、一个项目提案，一旦完成了它的使命——即推动决策、同步信息——它的价值就会随着时间的推移而递减。强求所有文档都保持最新是不现实的。

因此，作者提出了一个反直觉但极其有效的组织方法：按时间顺序组织文档

• 传统做法（按主题）：为每个功能或项目创建一个文件夹。这会导致文件夹价值不均，新旧文档混杂，甚至相互矛盾，查找困难。
• 推荐做法（按时间）：按年份 -> 迭代（Sprint）来组织。这种方式保留了清晰的时间线，当你通过搜索找到一篇文档时，能立刻了解它是在什么背景下、与哪些其他事件同时发生的。至于按主题查找？“那是搜索框的工作。”

架构师必备的“文档武器库”

文章最后还提供了一个高价值的附录，列举了几种在工程组织中最具影响力的文档类型。对于架构师来说，这些就是你的核心工具集：

• 架构概览 (The architecture overview)
  • 目的：帮助所有人快速理解系统的结构和设计。
  • 时机：构建新系统或重构现有系统之前。
• 开发设计 (The dev design)
  • 目的：在你写下大量代码前，获取关于实现思路的反馈。
  • 金句：“你写的文档越多，你需要写的代码就越少。” 一份好的设计文档能帮你避免因误解、错误假设和设计缺陷导致的返工。
• 项目提案 (The project proposal)
  • 目的：阐明一个项目的价值和成本，以获得资源分配。
  • 技巧：让你的提案易于被技术和非技术决策者“点头同意”。
• 开发者预测 (The developer forecast)
  • 目的：当你预见到一个决策可能带来负面结果时，以中立的、建设性的方式提出风险和缓解方案。
• 技术选型清单 (The technology menu)
  • 目的：在面临技术选型（例如，为新的 Go 微服务选择 RPC 框架）时，通过对比，帮助团队达成共识。

结论

从一个出色的开发者成长为一名卓越的架构师，其核心转变在于影响力的半径。代码的影响力作用于机器，而想法的影响力作用于人。文档，正是放大和部署后者影响力的核心媒介。

它不是编程的替代品，而是编程活动的“元编程”。一篇好的文档，可以在代码被编写出来之前，就解决掉项目中最大的瓶颈——那些关于人的沟通、协同和决策问题。对于所有追求技术卓越的工程师而言，将写作和文档管理提升到与编码同等重要的高度，是通往架构师之路的必经修炼。

资料链接：https://stackoverflow.blog/2025/08/20/documents-the-architect-s-programming-language/

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

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

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

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

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

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

本文永久链接 – 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技能再上一个新台阶！

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