1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
🚀 GitHub 最新「文件撰寫指南」懶人包
5/14 GitHub 釋出新文章〈Documentation done right: A developer’s guide〉，教開發者怎麼寫出快速、實用、易維護的技術文件。
chatGPT 摘錄精華如下：

📈 為什麼要重視文件？

* 協作更順暢：清楚的文件讓團隊與外部貢獻者同步，減少私訊問問題的頻率
* 新人更好上手：詳細導覽與基礎說明，能大幅縮短熟悉專案的時間
* 提高採用率：安裝簡單、說明清楚的專案更容易被使用、被推廣

✍️ 三大撰寫原則

* Clear：清楚易懂，盡量避免不熟悉的縮寫與專有名詞
* Concise：精簡為主，只寫必要內容，複雜情境另開文件
* Structured：重點先寫，搭配段落標題、粗體關鍵詞、條列方式排版

📚 文件四分法：Diátaxis 架構
GitHub 推薦使用 Diátaxis 架構來分類與撰寫文件，依照使用者需求分成以下四類：

* Tutorials（教學導覽）：手把手教學，適合新手從頭做起
* How-to Guides（任務指引）：解決特定問題的操作說明
* Explanation（原理解說）：補充概念、設計選擇背後的思維
* Reference（技術參考）：完整 API、指令等索引型資料

GitHub 也提供了範例 repo，可直接 fork 使用！

🛠️ 開始改善文件的三個步驟

* 先用 Diátaxis 檢查目前文件分類，有沒有哪類缺少
* 設計一份 Markdown 範本，讓大家統一格式與語氣
* 推動「先寫文件再寫程式」的開發習慣，降低知識斷層與技術負債

https://github.com/github/internal-documentation-example