防止文檔陷阱的 7 條準則

英語是開源社區的通用語言。為了減少翻譯成本，很多團隊都改成用英語來寫他們的文檔。 但奇怪的是，為國際讀者寫英語並不一定就意味著以英語為母語的人就佔據更多的優勢。 相反， 他們往往忘記了該文檔用的語言可能並不是讀者的母語。

我們以下面這個簡單的句子為例： 「Encrypt the password using the foo bar command。」語法上來說，這個句子是正確的。 鑒於動名詞的 「-ing」 形式在英語中很常見，大多數的母語人士都認為這是一種優雅的表達方式， 他們通常會很自然的寫出這樣的句子。 但是仔細觀察， 這個句子存在歧義因為 「using」 可能指的賓語（「the password」）也可能指的動詞(「encrypt」）。 因此這個句子有兩種解讀方式:

• 「加密使用了 foo bar 命令的密碼。」
• 「使用命令 foo bar 來加密密碼。」

如果你有相關的先驗知識（密碼加密或者 foo bar 命令），你可以消除這種不確定性並且明白第二種方式才是真正的意思。 但是若你沒有足夠深入的知識怎麼辦呢？ 如果你並不是這方面的專家，而只是一個擁有泛泛相關知識的翻譯者而已怎麼辦呢？ 再或者，如果你只是個非母語人士且對像動名詞這種高級語法不熟悉怎麼辦呢？

即使是英語為母語的人也需要經過訓練才能寫出清晰直接的技術文檔。訓練的第一步就是提高對文本可用性以及潛在問題的警覺性， 下面讓我們來看一下可以幫助避免常見陷阱的 7 條規則。

1、了解你的目標讀者並代入其中。

如果你是一名開發者，而寫作的對象是最終用戶， 那麼你需要站在他們的角度來看這個產品。 文檔的結構是否反映了用戶的目標？ 人格面具 persona 技術 能幫你專註於目標受眾並為你的讀者提供合適層次的細節。

2、遵循 KISS 原則——保持文檔簡短而簡單

這個原則適用於多個層次，從語法，句子到單詞。 比如:

• 使用合適的最簡單時態。比如， 當提到一個動作的結果時使用現在時:
  • " Click 'OK.' The 'Printer Options' dialog will appear. " -> "Click 'OK.' The 'Printer Options' dialog appears."
• 按經驗來說，一個句子表達一個主題；然而， 短句子並不一定就容易理解（尤其當這些句子都是由名片語成時）。 有時， 將句子裁剪過度可能會引起歧義，而反過來太多單詞則又難以理解。

• 不常用的以及很長的單詞會降低閱讀速度，而且可能成為非母語人士的障礙。 使用更簡單的替代詞語:

  • " utilize " -> "use"
  • " indicate " -> "show"，"tell" 或 "say"
  • " prerequisite " -> "requirement"

3、不要干擾閱讀流

將虛詞和較長的插入語移到句子的首部或者尾部:

• " They are not, however, marked as installed. " -> "However, they are not marked as installed."

將長命令放在句子的末尾可以讓自動/半自動的翻譯擁有更好的斷句。

4、區別對待兩種基本的信息類型

描述型信息以及任務導向型信息有必要區分開來。描述型信息的一個典型例子就是命令行參考， 而 HOWTO 則是屬於基於任務的信息；（LCTT 譯註：HOWTO 文檔是 Linux 文檔中的一種）然而， 技術寫作中都會涉及這兩種類型的信息。 仔細觀察， 就會發現許多文本都同時包含了兩種類型的信息。 然而如果能夠清晰地劃分這兩種類型的信息那必是極好的。 為了更好地區分它們，可以對它們進行分別標記。 標題應該能夠反映章節的內容以及信息的類型。 對描述性章節使用基於名詞的標題（比如「Types of Frobnicators」），而對基於任務的章節使用口頭表達式的標題（例如「Installing Frobnicators」）。 這可以讓讀者快速定位感興趣的章節而跳過對他無用的章節。

5、考慮不同的閱讀場景和閱讀模式

有些讀者在閱讀產品文檔時會由於自己搞不定而感到十分的沮喪。他們在一個嘈雜的環境中工作，也很難專註於閱讀。 同時，不要期望你的讀者會一頁一頁的進行閱讀，很多人都是快速瀏覽文本，搜索關鍵字或者通過表格、索引以及全文搜索的方式來查找主題。 請牢記這一點， 從不同的角度來看待你的文字。 通常需要折中才能找到一種適合多種情況的文本結構。

6、將複雜的信息分成小塊

這會讓讀者更容易記住和吸收信息。例如， 過程不應該超過 7 到 10 個步驟（根據認知心理學中的 米勒法則）。 如果需要更多的步驟， 那麼就將任務分拆成不同的過程。

7、形式遵循功能

根據以下問題檢查你的文字：某句話/段落/章節的 目的（功能）是什麼？比如，它是一個指令呢？還是一個結果呢？還是一個警告呢？如果是指令， 使用主動語氣： 「Configure the system.」 被動語氣可能適合於進行描述： 「The system is configured automatically.」 將警告放在危險操作的 前面 。 專註於目的還有助於發現冗餘的內容，可以清除類似 「basically」 或者 「easily」 這一類的填充詞，類似 「already existing 」 或「 completely new」 這一類的不必要的修飾， 以及任何與你的目標大眾無關的內容。

你現在可能已經猜到了，寫作就是一個不斷重寫的過程。 好的寫作需要付出努力和練習。 即使你只是偶爾寫點東西， 你也可以通過關注目標大眾並遵循上述規則來顯著地改善你的文字。 文字的可讀性越好， 理解就越容易， 這一點對不同語言能力的讀者來說都是適合的。 尤其是當進行本地化時， 高質量的原始文本至關重要：「垃圾進， 垃圾出」。 如果原始文本就有缺陷， 翻譯所需要的時間就會變長， 從而導致更高的成本。 最壞的情況下， 翻譯會導致缺陷成倍增加，需要在不同的語言版本中修正這個缺陷。

via: https://opensource.com/article/17/12/7-rules

作者：Tanja Roth 譯者：lujun9972 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive