防止檔案陷阱的 7 條準則 | Linux 中國

讓我們瞭解一下如何使國外讀者更容易理解你的技術文章。

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

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

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

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

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

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

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

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

3、不要幹擾閱讀流

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

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

4、區別對待兩種基本的資訊型別

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

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

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

6、將複雜的資訊分成小塊

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

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[4] 譯者：lujun9972 校對：wxy

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