每一個職業都有值得學習的地方。在軟體開發產業，工程師將寫高品質的程式碼技術傳授給其他人的秘訣，是經常總結可遵循的「哲學」與「原則」。但多數人只看到工程師打著複雜指令的一面，卻沒看到軟體設計背後的巧妙思維。

例如

• 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 個重點：

• 重點 1. 寫文件的通則是什麼
• 重點 2. 文件內容怎麼寫
• 重點 3. 文件發表要注意什麼
• 重點 4. 最後，檢查整份文件

寫文件的通則是什麼

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

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

• 先規劃架構 (Precursory)：在寫程式之前，先思考文件架構如何引導使用者
• 讓成員參與 (Participatory)：讓團隊內的開發者與產品端使用者 (例如業務、PO、PM) 一起參與，提供自己沒想到但可完善的內容

文件內容怎麼寫

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

有五個小原則可以遵循：

• 接受重複性的文件內容 (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)」 產品/技術文件，但可以將讀者的提問陸續更新到文件上。

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

本文轉貼自：PM 的學習力工具箱（原文連結）