Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

文件撰寫指引

為了讓 ROOST 各專案的文件更容易貢獻與維護，我們訂有若干偏好與預設作法。ROOST 專案應盡可能遵循這些文件撰寫指引。

Markdown

我們使用 Markdown 撰寫文件，因為純文字形式即可供人閱讀、GitHub 網頁介面原生支援，也廣泛用於開放原始碼專案。

具體而言，我們使用 GitHub Flavored Markdown（使用指引、規格），運用 GitHub 與網頁提供的額外格式能力。

README

每個專案的 repository 根目錄都必須有 README.md。這份關鍵文件應向貢獻者與可能的採用者介紹並推廣專案。README 應保持精簡，並包含下列內容。

  1. 專案簡介
  2. 專案服務的對象
  3. 專案解決的問題
  4. 協助理解專案的螢幕截圖

較簡單的專案也可在 README 中加入快速入門指引，說明如何在本機執行。篇幅較長的入門指引、背景資訊與架構資訊等內容，應放在 /docs 資料夾，並可從 README 連結，供希望深入了解的人閱讀。

Repository 內的 /docs 資料夾

除了 README 以外，專案文件應直接放在專案 repository 內的 docs/ 資料夾。這能讓自動化工具以一致方式建置及部署網頁文件網站，也能確保文件始終與本機 checkout 的程式碼並存，並可從 GitHub 網頁介面存取。

專案維護者可依實際需求組織文件，並可考慮納入下列內容。

  • 在本機執行專案的逐步指引
  • 開發環境需求，包括硬體或作業系統限制
  • 架構細節
  • 使用者文件，包括螢幕截圖與操作指引

檔名與結構

文件檔案通常應採用 kebab-case 命名，但 README.md 與 CONTRIBUTING.md 等有特殊處理方式的檔案除外。若多個頁面彼此相關，使用子資料夾，並以 README.md 作為首頁。例如下列結構。

  • docs/
    • README.md：文件首頁與簡介
    • faq.md：獨立的常見問題頁面，顯示為文件的子章節
    • user-guide/
      • README.md：使用者指南首頁與簡介
      • advanced.md：使用者指南的子頁面

如此可讓檔案在 GitHub 網頁介面與轉換成 mdBook 等文件網站後，都能順利瀏覽。

連結

連結至文件中的其他頁面時，使用能說明目的的連結名稱與相對連結，例如 進一步了解[特定功能](specific-feature.md)。這能提升螢幕閱讀器與搜尋引擎的使用效果，也能同時適用於 GitHub 網頁介面與建置後的 HTML 文件網站。連結至具有獨立資料夾的文件區段首頁時，應使用指向資料夾本身的相對連結，而非其 README.md，例如 詳情見[使用者指南](../user-guide/)。

mdBook 等文件網站產生工具會自動處理網頁版的連結目標轉換。

圖片

文件使用的圖片應存放於 docs/images/，檔名盡量精簡。為方便從 Markdown 引用，避免空格與其他特殊字元，並使用 kebab-case。相關圖片可放在子資料夾中，例如下列結構。

  • docs/
    • images/
      • overview.png
      • specific-feature/
        • overview.png
        • detail.png

若圖片不多，採用較扁平的目錄結構可能更簡單，例如下列結構。

  • docs/
    • images/
      • overview.png
      • specific-feature.png
      • specific-feature-detail.png

除非需要指定特定 HTML 屬性，否則使用 Markdown 引用圖片，例如下列寫法。

![精簡但具描述性的替代文字](docs/images/overview.png)

提示

以下是我們長期累積的經驗。

  • 文件量很大時，可依適用對象清楚區分。例如將非技術使用者指南，包括專案用途、功能與使用方式，與開發者技術文件，包括執行方式、程式碼結構與功能擴充方式分開。盡量不要跨越兩者邊界，例如使用者指南應避免放入程式碼區塊與 API 參考資料。

  • 不要重複資訊，改用連結。相同內容出現在愈多地方，文件愈容易過時或互相矛盾。使用者文件與開發者文件彼此連結是合理且可預期的作法，不需要在兩處重複同一份資訊。

  • 文件子資料夾最適合搭配簡短、少有或沒有子標題的 README.md。如此可讓資料夾中的其他子頁面，在 GitHub 網頁介面與產生的文件網站中更容易瀏覽。

  • 不必害怕把長頁面拆成較短的子頁面。若正在編輯的頁面長到難以掌握，可考慮把每個主要標題拆成獨立頁面。

  • 表格很適合少量資料，但表格欄位內應避免超過幾個詞，否則 Markdown 原始碼會很難閱讀與編輯。資料量較大時，可改用標題與段落。

文件網站

專案應產生網頁版文件，並透過 GitHub Pages 部署。預設網址為 roostorg.github.io/<project>，其中 <project> 是 GitHub repository 名稱。若專案文件會隨發行版本變動，文件網站應支援版本管理，例如下列網址。

  • main 分支位於 roostorg.github.io/<project>/latest/
  • 0.1 標籤位於 roostorg.github.io/<project>/0.1/
  • 0.2 標籤位於 roostorg.github.io/<project>/0.2/
  • 其他版本依此類推

ROOST 專案目前使用 mdBook 產生文件網站，並透過 GitHub Actions workflow，從帶標籤的發行版本輸出有版本區分的文件。

其他形式的文件

Issue 與 pull request 範本

每個專案都可以設定 GitHub issue 與 pull request 範本，確保 issue 與 PR 包含對該專案最有用的資訊。若專案 repository 沒有設定，則採用 ROOST 全組織的預設範本。

GitHub Wiki

專案不必使用 GitHub Wiki，但 Wiki 可用來放置與程式碼沒有直接連動、長期保存的補充文件，例如會議紀錄。請注意，將文件分散在 repository 內的 docs 與 Wiki 可能造成混淆，Wiki 也不應重複 repository 內的文件。