技術寫作例項解析 | 簡潔即是美

如同極簡主義的生活不代表苦行一樣，簡潔的寫作並不是用拙劣的文字苦哈哈地表達不完整的意思，而是一種更高的追求，一種經過凝練後的文字呈現。

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-