GNU 系統偏好的文件格式是 Texinfo 格式化語言。每個 GNU 套件都應該(理想情況下)具備 Texinfo 格式的文件,以供參考和學習之用。Texinfo 能夠使用 TeX 產生高品質的格式化書籍,並產生 Info 檔案。也可以從 Texinfo 原始碼產生 HTML 輸出。請參閱 Texinfo 手冊,可以參考紙本版本,或透過 info
或 Emacs Info 子系統 (C-h i) 取得線上版本。
現今,某些其他格式,例如 Docbook 和 Sgmltexi,可以自動轉換為 Texinfo。透過這種轉換方式產生 Texinfo 文件是可以接受的,只要結果良好即可。
請確保你的手冊對於完全不了解該主題並從頭開始閱讀的讀者來說是清晰易懂的。這表示一開始涵蓋基本主題,而進階主題則放在後面。這也表示在首次使用每個專有名詞時都加以定義。
請記住,GNU 手冊(以及其他 GNU 文件)的讀者是全球性的,並且將被使用多年,甚至數十年。這表示讀者可能具有非常不同的文化參考點。從現在起數十年後,除了老一輩的人之外,所有人都將具有非常不同的文化參考點;今天「眾所周知」的許多事物可能會被大部分遺忘。
因此,請盡量避免以依賴文化參考點才能正確理解的方式寫作,或者以會妨礙不認識這些參考點的人閱讀的方式提及它們。
同樣地,在你的用字遣詞(技術術語除外)、語言結構和拼字方面要保守:目標是讓十年前的讀者也能理解。在任何追求潮流的競賽中,GNU 的寫作甚至不應該有參賽資格。
如果與主題直接相關或作為題外話,偶爾提及空間或時間上 локалізований 的參考點或事實是可以的。當這些少數事物(無論如何都很突出)不再有意義時,更改它們不會花費太多功夫。
相對而言,當 GNU 和自由軟體運動的概念相關時,始終可以適當地提及它們。這些是我們訊息的核心部分,因此我們應該利用機會提及它們。它們是基本的道德立場,因此幾乎永遠不會改變。
程式設計師傾向於將程式的結構沿用為其文件的結構。但是這種結構不一定適合解釋如何使用程式;對於使用者來說,它可能是無關緊要且令人困惑的。
相反地,組織文件的正確方式是根據使用者在閱讀時會想到的概念和問題。此原則適用於每個層級,從最低層級(段落中句子的排序)到最高層級(手冊中章節主題的排序)。有時這種想法的結構與所記錄軟體的實作結構相符,但通常它們是不同的。學習編寫良好文件的重要部分是學會注意到何時你不經思索地將文件結構化得像實作一樣,阻止自己,並尋找更好的替代方案。
例如,GNU 系統中的每個程式可能都應該記錄在一本手冊中;但這並不表示每個程式都應該有自己的手冊。那樣做是遵循實作的結構,而不是幫助使用者理解的結構。
相反地,每本手冊都應該涵蓋一個連貫的主題。例如,我們沒有針對 diff
的手冊和針對 diff3
的手冊,而是有一本關於「檔案比較」的手冊,其中涵蓋了這兩個程式以及 cmp
。透過將這些程式放在一起記錄,我們可以使整個主題更清晰。
討論程式的手冊當然應該記錄程式的所有命令列選項及其所有命令。它應該提供它們用法的範例。但是不要將手冊組織成功能列表。相反地,按子主題邏輯地組織它。解決使用者在思考程式所做的工作時會提出的問題。不要只是告訴讀者每個功能可以做什麼,而是要說出它擅長做什麼工作,並展示如何將其用於這些工作。解釋推薦的用法是什麼,以及使用者應該避免哪些類型的用法。
一般而言,GNU 手冊應同時作為教學和參考。它應該設定為可以透過 Info 方便地存取每個主題,並且可以從頭到尾閱讀(附錄除外)。GNU 手冊應該為從頭開始閱讀的初學者提供良好的入門,並且還應該提供駭客想要的所有細節。《Bison 手冊》是這方面的一個很好的例子——請看看它,了解我們的意思。
這並不像乍聽之下那麼困難。將每一章安排為其主題的邏輯分解,但對章節進行排序,並編寫其文本,以便從頭到尾閱讀該章節是有意義的。在將書組織成章節時,以及在將章節組織成段落時,也要這樣做。重點是,在每個點上,解決前面文字提出的最基本和最重要的問題。
如有必要,在手冊的開頭新增額外的章節,這些章節純粹是教學性質的,涵蓋該主題的基礎知識。這些章節為初學者理解手冊的其餘部分提供了框架。《Bison 手冊》提供了如何做到這一點的一個很好的例子。
為了作為參考,手冊應該有一個索引,列出程式的所有函數、變數、選項和重要概念。對於簡短的手冊,一個綜合索引就足夠了,但有時對於複雜的套件,最好使用多個索引。《Texinfo 手冊》包含關於準備良好索引條目的建議,請參閱 《製作索引條目》 在 GNU Texinfo 中,並參閱 《定義索引條目》 在 GNU Texinfo 中。
不要使用 Unix man page 作為編寫 GNU 文件的模型;它們大多數都很簡潔、結構不良,並且對基本概念的解釋不足。(當然,也有一些例外。)此外,Unix man page 使用的特定格式與我們在 GNU 手冊中使用的格式不同。
請在手冊中包含一個電子郵件地址,用於報告手冊文本中的錯誤。
請不要使用 Unix 文件中使用的術語「pathname」;請改用「file name」(兩個詞)。我們僅將術語「path」用於搜尋路徑,即目錄名稱列表。
請不要使用術語「illegal」來指稱電腦程式的錯誤輸入。請對此使用「invalid」,並保留術語「illegal」用於法律禁止的活動。
請不要在函數名稱後面寫 ‘()’ 僅僅為了表明它是一個函數。foo ()
不是一個函數,它是一個沒有參數的函數呼叫。
請盡可能堅持使用主動語態,避免被動語態,並使用現在時,而不是未來時。例如,寫「函數 foo
傳回一個包含 a 和 b 的列表」,而不是「將傳回一個包含 a 和 b 的列表。」主動語態的一個優點是它要求你陳述句子的主語;使用被動語態,你可能會省略主語,這會導致含糊不清。
當文法要求時,使用未來時是恰當的,例如,「如果你輸入 x,電腦將在 10 秒內自我毀滅。」