如同极简主义的生活不代表苦行一样,简洁的写作并不是用拙劣的文字苦哈哈地表达不完整的意思,而是一种更高的追求,一种经过凝练后的文字呈现。
The ability to simplify means to eliminate the unnecessary so that the necessary may speak. - Hans Hofmann
为什么要简洁?
在技术传播中,文字的简洁至少有以下两方面的考量:
1)提高技术文档的易读性。
从用户(即技术文档的受众)的角度来看,易读性非常重要。
通常,技术文档的读者都是有实际需求才去读的。例如,用户不清楚如何配置或如何使用某个产品,试图从产品使用指南中找到答案。
而人们对于陌生的事物或者不熟悉的事物常常会感到一脸迷茫、手足无措,不是因为某件事有多难,大多数时候只是因为你从未做过、不知道如何做而已。
那么,为了让用户快速地找到自己想要的答案,技术文档的易读性就分外重要。用户不会想读晦涩难懂的文字,也没有心思去品评你的用词是否足够华丽足够有文采。用户很忙的,用户的时间很宝贵。
用户需要的是足够清晰易懂、足够简洁明了的内容。
2)节省文档占用的空间。
从技术文档输出者的角度来看,有必要保持文档简洁。
如今,文档的存在形式多种多样,既可以是纸质的印刷内容,也可以是 PDF/chm 等多种格式的电子书。虽然看起来不如第一点那么重要,但从宏观来看,保持文档的简洁可以节约文档输出时耗费的时间成本和金钱成本。
如何做到简洁?
尽管说起来容易做起来难,有些原则还是要知道的。
且先呈上 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 章节的详细内容,书中有对每一条原则的解释和举例,这里不再详述。
技术写作实例解析说“简洁”
实例背景
本文实例摘取自开源分布式 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:
In the process of backing up and restoring data, use the following tools: ...
Updated Version:
Use the following tools for data backup and restoration: ...
上述例句中,把 "use" 一词提前,对句子进行删减整合,使句子更加简洁。试着读一下原句与修改后的句子,要理解所表达的意思,修改后的版本明显花费的时间更少。
实例 4
Original Version:
stats_buckets
: the buckets of statistics information
Updated Version:
stats_buckets
: the buckets of statistics
这个例子对应的是简洁的六项原则中的第三个:Delete words implied by other words. "statistics" 一词指“统计数据”,本身已有信息之意,故无需再加 "information" 一词来重复。
小结
随着年龄的增长,个人越来越喜欢极简主义的生活,而文字的凝练非一朝一夕可以达成。技术文档像是没有感情的一种存在,却也个性鲜明,简洁就是它的美。
你可能想读:
书单 | 有哪些技术传播从业者必知必看的书籍?
若脱离理解,直译得再正确又有何意?
优质译文不应止于正确,还要 Well-Organized
写在入职技术型创业公司 PingCAP 一个月之后
-END-
网友评论
Original Version:
In the process of backing up and restoring data, use the following tools: ...
Updated Version:
Use the following tools for data backup and restoration: ...
我觉得,在没有上下文的情况下,original version还有一个问题,In the process of ... 会有多种理解,会让读者疑惑。