Basic rules for writing technical documentation

從 0 開始學習技術寫作 #3-寫軟體技術文件有哪些可遵循的原則 ?

每一個職業都有值得學習的地方。

在軟體開發產業，工程師將寫高品質的程式碼技術傳授給其他人的秘訣，是經常總結可遵循的「哲學」與「原則」。

但多數人只看到工程師打著複雜指令的一面，卻沒看到軟體設計背後的巧妙思維。

例如

Don’t repeat yourself (DRY): 減少軟體開發時的重複性工作 (aka 不要重複造輪子)
Keep it simple, stupid (KISS): 系統設計應該要以「簡潔 (Simplicity)」為目標，而非「複雜 (Complicated)」
Code reuse: 重複使用已經編寫過的程式碼 (軟體)，來建立新的軟體。程度低到高分別如 Copy-Paste > 建立 Function (函式)/ Object (物件) > 建立函式庫 (Library) > 建立套件 (packages)/ 框架 (framework)

「哲學」與「原則」是學習開發程式時的指引，按照大方向做就能產品一定品質的成果。

如果我們要將工程師寫程式的思維套用到「寫文件」上，可以如何借鏡呢？以下來自 Write the Doc 和我的個人經驗，有 4 個重點:

「寫文件」可以拆成 3 部分說明:(1)內容 (2)發表 (3)整份文件。

先講大原則，所有的文件 (產品/技術) 都應該

「文件內容」是告訴讀者如何使用我們的產品/程式。

有 5 個小原則可以遵循:

接受重複性的文件內容 (Accept some Repetition In Documentation): 寫 Code 要盡量遵守「不要重複輪子」原則，但寫文件必須妥協。例如商業邏輯的內容，很多時候都會重複提及
可概覽 (Skimmable): 用結構化的方式組織內容，幫助讀者快速掃過他們「需要讀的」跟「可省略的」。例如使用容易理解的大文章標與次標
有範例 (Exemplary): 在教學內容中一定要加入使用範例。例如說明 Order API 的時候，可以用「若要建立 1 張 TWD.1000 的訂單，API 參數可以這樣帶」
一致性 (Consistent): 保持相同的寫作語氣與格式。例如大量使用列點 (Bullet Point)，讓文件風格維持俐落感
即時性 (Current): 過時的資訊就是錯誤資訊，確保文件上的內容跟系統/程式碼功能是一致的。例如訂單 UI 近期有更新，則文件的截圖也必須同步更新

文件寫好後準備對外發布，顧好眉角才能讓文件「被看到」與「被看懂」。

有 5 個小原則可以遵循:

可被找到的 (Discoverable): 檢查系統畫面中可以插入文件連結的地方，確保使用者可以看到教學文件。例如在使用率極高的 Dashboard, Order 頁面，加入文件連結的按鈕
強調的 (Addressable): 在畫面上提供文件連結時，告訴讀者他應該要看哪裡。方式有 (1)文字提醒 (例如 "請看此連結頁面的第二段") (2)錨點跳轉 (例如 "example#section2")
循序的 (Cumulative): 文件排序必須按照讀者的理解順序排列。例如一份對外 API 的教學文件，內容的擺放順序應該是「API Overview」> 「API 取授權 (Auth)」>「各功能 API 操作」
完整的 (Complete): 文件中講解的概念種類要有一致性，只能是 (1) 全講 (2) 不講。例如在 Glossary Overview (產品名詞介紹) 中，如果只是條列名詞就不要提及某個名詞的細節 ; 如果要講解某個名詞細節，則所有名詞都需要解說
漂亮的 (Beautiful): 為了讓文件好閱讀，盡可能有意地維持整齊、一致性的文字排版。例如這篇文章就刻意維持 Bullet point 的排版

確保文件能 “最大程度地” 回答讀者的問題。

我們不可能寫出一份 “完整的 (Complete)” 技術文件，但可以將讀者的提問陸續更新到文件上。

文件像是一款產品，可以持續迭代。

Last updated 1 year ago