## 如何寫作科技文檔 科技文檔相對特殊，把它寫得通俗易懂而又不失簡潔，幾乎是一件不可能完成的任務。 盡管如此，通過有意識的使用一些技巧，還是能夠盡可能的接近這個目標。 我這里有一些個人的經驗，請看下面的三種表述: * _第一個例子[[1](pr06.html#ftn.id3047361)]_ ``` 就像前面提到的，所有USE標記都聲明在USE變量里面。 為了讓用戶能方便地查找和選擇USE標記，我們提供了一份默認的USE設定。 這些設定是我們覺得Gentoo用戶通常都要用到的USE標記的集合。 這個默認設置在make.defaults文件──你的profile的一部分──里聲明。 你的系統使用的profile是符號鏈接/etc/make.profile所指向的目錄。 每個profile疊加于某個更大的profile之上，最終的結果是這些profile的并集。 初始profile是base profile（/usr/portage/profiles/base）。 ``` * _第二個例子_ ``` /etc/make.profile/目錄是一個符號鏈接，里面包含一些make.defaults文件，實際指向的是以下文件， 可以在這些文件中設置USE標記(不可更改) ``` * _第三個例子_ ``` /etc/make.profile/目錄是一個符號鏈接，里面包含一些make.defaults文件，放置開發者設置的USE標記： ``` **目的明確.?** 手把手的操作步驟與宏觀的概念描述、面向新手與面向老手，肯定會有很大的不同。要根據需要決定你的方向 第一個例子是給忠實用戶使用的權威官方文檔，后面例子中是向新手介紹的簡要說明，目的不一樣，所以介紹的詳細程度不同 **簡明清晰.?** 在有些時候，要改變一下思路，從另一個角度敘述(在翻譯文檔時，這種技巧比較有用)。 第二個例子是最常見的介紹方式，它暴露了過于復雜的細節：實際指向、不可更改，而沒有說明關鍵細節：開發者設置，還有一些冗余信息：可以在這些文件中設置 第三個例子中，在介紹了USE的概念之后，說明這些USE是開發者設置的，就可以暗示很多事情。如果說“系統默認、不可更改……”你最好說明為什么，因為“不可更改”這種聲音，對于Linux用戶來說無疑有些刺耳…… **控制復雜度.?** 描述的復雜度必須控制，不要假定用戶對Linux很熟悉……如果所有的文檔都使用這樣的假定，那么大多數用戶很難熟悉Linux 在分析了自己的目的之后，你要有一個取舍。你要確定讀者是否需要明白什么是“profile” 針對“profile”，如果不深入解釋，有點虎頭蛇尾，而科技文檔的一個很重要的特點是“完整”；如果解釋，則增加了一個不必要的分支 **不要過度隱喻.?** 對于軟件，只要不是在源代碼的層面上描述，都算作隱喻。只是有的隱喻不明顯，如啟動、運行(它們的喻體是符號化的“系統”)；而有些隱喻則比較形象，例如電視機、遙控器 如果不是難以描述的概念，不要用隱喻 如果確實需要使用形象的隱喻，特別是在短時間內多次使用，請確保喻體的相關性。電視機:系統、遙控器:終端 這樣的比喻容易理解，而電視機:系統、手機:終端 的隱喻，多少令人費解 **限制術語的使用.?** 術語本身擁有需要解釋的特點。 像第一個例子中的“并集”，這是集合中的術語，并不是每個讀者都熟悉集合的概念；而“并集”指多個集合相加，熟悉集合概念的讀者，可能會深究被加在一起的集合……如果不引入這個術語也可以解釋清楚，那么不要引入它 **基礎概念.?** 不要認為介紹基礎概念是吃力不討好的工作，盡管讀者可以從操作步驟中得出基礎概念 既然大多數的描述都是隱喻，在描述基礎概念的時候，不要顧忌使用隱喻。讀者得到一個基本概念之后，可以更容易的理解接下來的描述。(“解釋學之弧”) **雕琢實例.?** 不要試圖通過一個實例闡釋許多個概念，不要隨手抓一個什么東西當作實例。應該構建最簡化的實例，每個實例只講一件事(K&R 《The C Programming Language》) **充分利用文檔工具的特性.?** 腳注，calloutlist 多數文檔工具都可以使用腳注，使用腳注作簡短的說明，可以確保在不增加分支的情況下，對概念作必要的說明 calloutlist用來作密集注釋。雖然你可以把這部分內容分成多段描述，但是使用calloutlist，可以清晰的列出主干，更容易閱讀[[2](pr06.html#ftn.id3025645)] **厚積薄發.?** 控制表達的沖動。很多文檔作者都容易犯這樣的錯誤，旁征博引、滔滔不絕……(《鳥哥私房菜》)可能你知道的確實挺詳細，但請記住，你不是自說自話，而是寫給讀者。請考慮一下讀者希望看到什么內容，而不是你想寫什么內容 * * * > [[1](pr06.html#id3047361)] 本例來自[gentoo中文手冊](http://www.gentoo.org/doc/zh_cn/handbook/) > [[2](pr06.html#id3025645)] 另一方面，只有 DocBook 支持 calloutlist，這意味著，如果從 DocBook 轉換到其它格式，calloutlist 將會制造一些麻煩 在代碼環境中使用的注釋，很大程度上可以替代 calloutlist的作用