技术写作实例解析 | 简洁即是美

Lilian Lee 技术传播那些事儿

如同极简主义的生活不代表苦行一样，简洁的写作并不是用拙劣的文字苦哈哈地表达不完整的意思，而是一种更高的追求，一种经过凝练后的文字呈现。

The ability to simplify means to eliminate the unnecessary so that the necessary may speak. - Hans Hofmann

1. 为什么要简洁？

在技术传播中，文字的简洁至少有以下两方面的考量：

1）提高技术文档的易读性。

从用户（即技术文档的受众）的角度来看，易读性非常重要。

通常，技术文档的读者都是有实际需求才去读的。例如，用户不清楚如何配置或如何使用某个产品，试图从产品使用指南中找到答案。

而人们对于陌生的事物或者不熟悉的事物常常会感到一脸迷茫、手足无措，不是因为某件事有多难，大多数时候只是因为你从未做过、不知道如何做而已。

那么，为了让用户快速地找到自己想要的答案，技术文档的易读性就分外重要。用户不会想读晦涩难懂的文字，也没有心思去品评你的用词是否足够华丽足够有文采。用户很忙的，用户的时间很宝贵。

用户需要的是足够清晰易懂、足够简洁明了的内容。

2）节省文档占用的空间。

从技术文档输出者的角度来看，有必要保持文档简洁。

如今，文档的存在形式多种多样，既可以是纸质的印刷内容，也可以是 PDF/chm 等多种格式的电子书。

虽然看起来不如第一点那么重要，但从宏观来看，保持文档的简洁可以节约文档输出时耗费的时间成本和金钱成本。

2. 如何做到简洁？

尽管说起来容易做起来难，有些原则还是要知道的。

且先呈上 Joseph M. Williams 的 Style: Lessons in Clarity and Grace 一书中关于行文简洁的六项原则，供大家细细琢磨，付诸实践，在技术写作中参考。

Six Principles of Concision:

Delete words that mean little or nothing.
Delete words that repeat the meaning of other words.
Delete words implied by other words.
Replace a phrase with a word.
Change negatives to affirmatives.
Delete useless adjectives and adverbs.

感兴趣的小伙伴可以去看下此书 Lesson 9: Concision 章节的详细内容，书中有对每一条原则的解释和举例，这里不再详述。

3. 技术写作实例解析说“简洁”

实例背景

本文实例摘取自开源分布式 NewSQL 数据库产品 TiDB 的技术文档。

实例 1

Original Version:

When you execute the task of analyzing regular columns, you can use the tidb_distsql_scan_concurrency parameter to control the number of Region to be read at one time.

Updated Version:

When you analyze regular columns, you can use the tidb_distsql_scan_concurrency parameter to control the number of Region to be read at one time.

这个例子要说明的是：若能用一个词把意思表达清楚，就不要用多个词。这里对应上文六项原则中的第四个原则：Replace a phrase with a word.

上述例句中，"analyze" 一词足以表达 "execute the task of analyzing" 要传达的意思，而且更为简洁易懂。替换之后，仿佛对句子进行了瘦身，甩掉了一身赘肉，清爽至极。

实例 2

Original Version:

These system tables contain grant information about user accounts and the privileges held by them: ...

Updated Version:

These system tables contain grant information about user accounts and their privileges: ...

上述例句中，"their privileges" 足以替代 "the privileges held by them"。行文的简洁需要时刻自我提醒，毕竟 "easy to state but hard to follow"。

实例 3

Original Version: