 |
Image credits :
April Killingsworth. Modified by Rikki Endsley. CC BY-SA 2.0.
|
使用wiki來建立文件並不是一個新的想法。無數個開源專案都這麼做。如果你正在尋找一種快速編寫和發布文件的方式，那麼wiki可以代替許多技術寫作的工具。
儘管如此，許多wiki的文件並不是被有效使用的。你可以透過一些技術來使你wiki上的文件更有效被使用，更有可讀性。不論是在wiki上新增文件還是將已經存在的移動到wiki上，你都可以使用這些小技巧。
不要僅限至於"書"
我花了20多年的時間在與技術作家溝通中學到了一個教訓：沒有人喜歡閱讀厚的手冊。如果你開始在wiki上編寫文件或將文件移動到wiki上，沒關係，那些wiki的內容就只是線上版的厚手冊而已。手冊中的一整個章節通常可以成為wiki的單個頁面，並且有大量的文字和圖片。
事實上應該要遠離"書"的形式。將文件分成可管理的區塊。一份wiki的有效文件應該是這些區塊的結合，而不是只是把大量的訊息交給讀者自行篩選。
你可以使用"基於主題的寫作"。透過這個方法，將文件的每個部份(例如：參考資料、過程)變成單個wiki頁面(或是主題)。例如：對章節的介紹是一頁，過程則是另一個頁面，等等的。如果你的文件中有很長的過程，也可以將它們分成幾個較短的頁面。
你可能會有一小段內容，像單個段落的概述或一個兩個步驟的過程。把這樣的內容放在獨立的頁面其實沒有意義。事實上，這樣的頁面看起來並不合適。應該不要將它們另外獨立出來。或許會得到一段稍長的wiki頁面，但是後者的頁面會有更多人接受。
導航很重要
採取” 基於主題的寫作”可能會使文件內容太過跳躍，其中少部分(如果有的話)的主題才會存在連續性，但大部分並非如此。
你可以透過適當的導航來解決這個文件不通順的問題。精心設計的導航能幫助讀者輕鬆且快速的瀏覽wiki上的主題，並找到他們所需要的任何訊息。
好的導航應該要包括以下幾點：
- 一個詳細的目錄，讀者可以透過這個目錄到wiki的任何頁面
- 連向相關內容的連結頁面，例如：安裝和升級過程
- 頁面結尾有可前往相關訊息的連結
添加連到wiki頁面是需要大量的手動去完成的，不過這麼做是值得的，因為它能使讀者們有更好的使用體驗。
好看也很重要
文件必須要有好的審美策略。它必須是友善的，不只在寫作方面，呈現方式也是。它應該要很容易被閱讀，看起來有吸引力，一看就是你很想要的東西那樣。
-- Common Knowledge Foundation共同創辦人Adam Hyde
大多數出現在wiki的文件看起來像….好吧，看起來像是在wiki的文件。這沒有什麼問題，但讀者會期望多一點東西，這也代表需要讓wiki本身有吸引力一點。它看起來應該要有你專案網站的感覺。至少，考慮使用wiki默認主題之外的其他選擇。
沒有人會喜歡標題和抬頭是使用CamelCase(駱駝式命名法)的wiki。CamelCase在頁面標題出現是很難看的 – 令人不快的視覺刺激。應該要在網頁標題中加入空格。例如：不是"WritingASimpleMacro"而應該是"Writing A Simple Macro"。添加這些空白會使wiki頁面有更大的吸引力。
一個最後的想法
用於編寫和提供任何類型的文件上，Wiki是一個非常靈活且強大的工具。確保wiki能有效使用需要一些工作，但是這些額外的工作能幫助讀者集中在文件中，並使它易於被使用。
-
後記
文件說明其實在資訊領域非常重要，這也是溝通的一種方式，像是目前使用最多的README，能提供使用者快速了解程式是如何運作和如何使用，本文中提到wiki的技巧我想也能夠應用在其他種類的文件說明中。其實還蠻常聽說業界通常是將前者的全部打掉自己重新編寫，不過這樣有很大的風險，而且不能保證不會遇到之前所遇到的問題，或許之前的問題已經被解決，只需要繼續使用即可。因此如何能讓自己作品可讀性和可重複利用性提升我覺得是必學的課題。
沒有留言:
張貼留言