美文网首页技术传播那些事儿
技术写作实例解析 | 简洁即是美

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

作者: Lilian_Lee | 来源:发表于2017-10-10 20:15 被阅读41次

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

    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:

    1. Delete words that mean little or nothing.

    2. Delete words that repeat the meaning of other words.

    3. Delete words implied by other words.

    4. Replace a phrase with a word.

    5. Change negatives to affirmatives.

    6. 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-

    相关文章

      网友评论

      • Joy的未来十年:关于实例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: ...

        我觉得,在没有上下文的情况下,original version还有一个问题,In the process of ... 会有多种理解,会让读者疑惑。

      本文标题:技术写作实例解析 | 简洁即是美

      本文链接:https://www.haomeiwen.com/subject/jbubyxtx.html