“今晚月色真美”这种朦胧的言辞是不适用技术文档的。最好不要让用户“反复推敲你句意有几种”，也不要让用户感到你“稠密的心思没几人能懂”。在技术写作的世界里，清晰、直白、明确才是正途。
Easy reading is damn hard writing. — Nigel Hawthorne
为什么要清晰？
清晰 (clarity) 是好的技术文档的基本要求之一。
一方面，清晰有利于用户快速而正确地理解文档，避免因歧义、模棱两可引起的操作不当等问题；另一方面，清晰有利于提升文档的规范性，便于文档维护。
如何做到清晰？
如果你想系统地了解技术文档中如何做到清晰，可以参考 Developing Quality Technical Information 一书 Chapter 5: Clarity 这一章节，里面有详细的规则和实例讲解。具体的七项规则如下：
要在实际的技术文档写作中运用好这些规则，还需多多实践。本文选取其中常用的 Avoid ambiguity 这条，结合实例跟大家分享具体该如何运用。
技术写作实例解析说“清晰”
说明：本文实例摘取自开源分布式 NewSQL 数据库产品 TiDB 的技术文档。
避免模糊不清、模棱两可的具体做法：
- 使用意思明确的词
- 避免名词和动词难以区分
- 重要操作的描述要足够清晰具体
实例 1
Original:
You can view the statistics status through certain statements.
Updated:
You can view the statistics status using the following statements.
本例句的上文是文档内的小标题，下文是关于查看不同类型统计信息的语句和返回结果。在 Original 版中，through 和 certain 这两个词都不清晰，可能会给用户造成困惑。
through 一词常常被用来表达中文的“通过”，对应的意思是 by means of “凭借”。use 一词意为“使用”，则更加清晰明了。
certain 一词常常被用来表达中文的“某”，本身带有不明确的意思，如：某些原因；类似的还有 some。所以，一般来讲，技术文档中应尽量避免此类词。
回到例句中来，将 through certain 改为 using the following 后，句子的表意明显更加清晰。用户可以很容易地理解，使用下文的语句即可查看统计信息的状态。
实例 2
Original:
The TiDB System Database is similar to MySQL, which contains tables that store information required by the server as it runs.
Updated:
The TiDB System Database is similar to MySQL, which contains tables that store information required by the server when it runs.
在 Original 版中，as 一词作为连词时虽然有 when 的意思，但是 as 作连词时还有多个其它词意，如：因为；以……方式；尽管。
when 一词的意思比较明确，就是“当……时”。所以，将 as 改为 when 便可避免词意的纠葛。
实例 3
Original
Updated
因为 update 一词本身既可作名词，也可作及物动词，所以 update time 这个表达就有歧义了，既可以表示更新时间这个操作，又可以表示更新的时间。
将 update time 改为 the time of the update，便可以清楚地知道，此处的 update 是名词，指的是更新的时间。
实例 4
Original:
A complete TiDB cluster contains PD, TiKV, and TiDB. To start the database service, follow the order of PD -> TiKV -> TiDB. To close the database service, follow the reverse order of start-up.
Updated:
A complete TiDB cluster contains PD, TiKV, and TiDB. To start the database service, follow the order of PD -> TiKV -> TiDB. To stop the database service, follow the order of stopping TiDB -> TiKV -> PD.
本例句来自 TiDB Binary 部署文档的概述部分，描述了启动和关闭数据库服务的顺序。在 Original 版中，虽然表意没错，指按照启动的相反顺序关闭服务。但对于这种重要操作，更好的做法是将关闭服务的顺序清晰明确地写出来，用户无需思考，直接按此顺序操作即可，避免可能的操作失误。
小结
技术文档的目的不是让作者明白，而是让用户明白。清晰的表达可以让用户一看就理解，提高对产品的满意度。Developing Quality Technical Information 一书所列的七项清晰规则需要 Technical Writer 在写作实践中融汇贯通。小伙伴们若是有什么心得，欢迎一起交流探讨呀~
你可能想读：
书单 | 有哪些技术传播从业者必知必看的书籍？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
写在入职技术型创业公司 PingCAP 一个月之后
-END-
网友评论