寫軟體技術文件有哪些可遵循的原則?注意 4 個重點,幫助你寫出一份好閱讀的產品 / 技術文件

寫軟體技術文件有哪些可遵循的原則?注意 4 個重點,幫助你寫出一份好閱讀的產品 / 技術文件

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

例如

  • 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) 一起參與,提供自己沒想到但可完善的內容

文件內容怎麼寫

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

有 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)」 產品/技術文件,但可以將讀者的提問陸續更新到文件上。

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

 

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

本站所有文章未經事先書面授權,請勿任意利用、引用、轉載。