程式碼要有文件

文件記錄周全的原始碼能幫助人們瞭解該原始碼的作用與使用方式。文件紀錄是幫助人們快速上手如何使用程式基 底，並做出貢獻的關鍵。

需求規定

• 程式基底的所有功能、政策及原始碼，都「必須」以可清楚瞭解的用語描述，讓懂程式基底目的用途的人也能夠理解。
• 程式基底文件「必須」說明如何安裝與執行軟體。
• 程式基底文件「必須」為關鍵功能舉出範例。
• 程式基底文件「應該」包含精要的說明，讓一般大眾和記者等廣泛的利害關係人都能清楚明白。
• 程式基底文件「應該」有一部分用來說明，如何安裝與執行原始碼的單機版；如果有必要，也應該包含測試資料集。
• 程式基底文件「應該」包含所有功能的範例。
• 程式碼文件「應該」描述程式基底的主要組件或模組，以及其彼此之間的關係，例如以高層架構圖表示。
• 「應該」要有針對文件品質的持續整合測試。
• 「可選擇」是否在程式基底文件中，包含讓使用者想要立即使用程式基底的範例。

測試方式

• 確認文件內容能讓其他利害關係人、其他公家機關的專業人士，以及一般大眾，都可以清楚明白。
• 確認文件有說明如何安裝與執行原始碼。
• 確認文件有包含主要功能的範例。
• 向一般大眾的成員以及記者確認，他們是否能明白文件當中的精要說明。
• 檢查單機版原始碼的安裝與執行的步驟說明，確認能順利執行系統。
• 檢查文件中列舉的所有功能都包含範例。
• 檢查文件中是否包含高層架構圖，或類似的組件關係圖表。
• 確認整合測試有包含到程式碼文件品質，例如確認生成的文件是否正確，並檢查連結與圖片等。

公共政策制定者：需要的工作

• 定期查看程式基底中非政策程式碼的變動情況。
• 針對如何讓非政策文件更清楚易懂提供意見回饋。

管理人員：需要的工作

• 嘗試使用程式基底，並提供您的意見回饋來讓政策與原始碼文件改善得更加清楚。舉例來說，可以自問目前的文件是否足以說服另一個公家機關的管理人員使用這套程式基底？
• 確保您同時瞭解政策、原始碼以及文件內容。

開發人員與設計師：需要的工作

• 定期查看程式基底中非原始碼部分的變動情況。
• 針對如何讓非原始碼文件更清楚易懂提供意見回饋。

延伸閱讀

• Write the Docs《文件指南》。