代码之外的必修课:顶级技术文档风格指南如何提升你的工程效率
本文永久链接 – 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. 拥抱主动语态,指令明确无误
主动语态让指令更直接、更有力。在指导性文档中,这能显著降低读者的认知负荷。
不推荐 (被动语态) | 推荐 (主动语态) |
---|---|
Linuxconf can be started by typing … | Type … to start Linuxconf. |
新的配置可以被应用通过重启服务。 | 重启服务以应用新的配置。 |
对开发者的价值:当用户(或未来的你)阅读操作手册时,清晰的指令意味着更低的出错率和更快的解决问题速度。
2. 杜绝冗余,尊重读者的时间
避免使用不必要的填充词,让每一句话都言之有物。
冗余 | 精炼 |
---|---|
Perform the installation of the product. | Install the product. |
This problem is located on the /dev/sda1 partition. | This problem is on the /dev/sda1 partition. |
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技能再上一个新台阶!
商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求,请扫描下方公众号二维码,与我私信联系。
© 2025, bigwhite. 版权所有.
Related posts:
评论