說明文件類型

說明文件是所有產品或功能的重要組成部分，可讓使用者瞭解如何運用已導入的功能。本文件提供快速且簡單的文件類型參考資料。

如要瞭解一般說明文件標準 (包括檔案類型、位置和一般色調)，請參閱 Fuchsia 說明文件標準。如需字詞選擇、樣式和結構的具體指南，請參閱「Fuchsia 說明文件樣式指南」。

程序 (指南)、概念或參考說明文件

大多數的說明文件可分為以下類別：

  • 程序 (指南)
    • 開始使用 - 說明文件，提供如何完成 Fuchsia 開發人員環境設定流程，例如下載及建構 Fuchsia。這些項目位於 /docs/get-started 下方。
    • 開發 (或指南) - 說明文件，提供完成任何 Fuchsia 相關任務的逐步程序。這些全都位於 /docs/development/ 下。
  • 概念 - 說明文件，協助您瞭解如 Fuchsia 中的功能模組等概念。這類說明文件位於 /docs/concepts 下方。
  • 參考資料 - 提供系統部分相關資訊 (例如 API 參數或 FIDL) 相關資訊的說明文件。這些項目位於 /docs/reference/ 下。大部分的參考說明文件會自動產生。

如果您打算向使用者說明如何使用特定功能，並引導對方完成簡單的編號步驟，則應撰寫程序文件。具體性文件通常會提供一或多個對使用者可能有幫助的範例，以強化概念性文件中的概念。

如果想說明產品概念，建議你撰寫概念文件。概念文件說明特定概念，但絕大部分不包含實際範例。它們提供重要事實、背景和圖表，協助讀者對產品或主題有基本瞭解。請勿說明您的目標對象應熟悉的業界標準，例如 TCP/IP。您可以說明這個概念如何與您的功能相關，但切勿解釋該產業標準概念背後的基本概念。

如需提供系統部分的相關資訊，包括但不限於 API 和 CLI，您應撰寫參考文件。參考說明文件應讓使用者瞭解如何快速輕鬆地使用特定功能。

相關說明文件

程序說明文件應盡量簡短，說明文件中的每項工作也應盡量避免執行超過 10 個步驟。您應將長時間執行的程序細分為多個子工作，嘗試讓使用者能夠管理任務。

舉例來說，如果您要撰寫處理犬隻保養的程序文件，內容表格可能會如下所示：

如何照顧狗：

  • 餵狗
  • 洗狗
  • 修剪狗的指甲
  • 撫摸狗的頭髮

一般程序說明文件指南

  • 每項工作或子工作都應有一個段落，讓使用者瞭解工作內容，以及使用者在執行工作或子工作後應執行的動作。
  • 提供螢幕截圖或圖形，協助使用者瀏覽使用者介面 (UI)。

  • 程序文件不應要求使用者解釋任何概念，但應在使用者不知道某個概念時參考概念文件。舉例來說，帶有概念文件參照的程序可能如下所示：

    以適當的設定來設定伺服器。如要進一步瞭解伺服器設定，請參閱「伺服器設定」。

  • 處理程序時避免為使用者提供多個可以選取的路徑。如果您避免提供使用者選項，說明文件應將所有使用者導向相同的最終結果。

  • 如果程序文件適合初學者，請避免加入您認為較適合進階使用者的程序。如果您的文件適用於進階使用者，請先說明，並在逐步說明操作或程式碼研究室之前，向他們提供必備條件清單。

  • 如要在程序說明文件中納入程式碼範例，請參閱程式碼範例樣式指南中詳述的最佳做法

概念說明文件

概念說明文件應簡明扼要，且大部分內容不應超過 1 頁。如果您需要撰寫多個頁面來說明某個概念，請考慮使用標題將這個概念分割為多個子概念。保持文件簡介可讓您達成以下目標：

  • 沒有讓讀者覺得文字難以閱讀。
  • 避免在讀者閱讀文件時遺失讀者。

第一段應試著提供文件的簡短摘要，這樣應該能讓使用者快速閱讀文件、決定文件內容，以及這是否與想學習的內容相關。如果文件有多個標題，則應在第一個段落之後加上項目符號清單，並在其中列出高階標題。

請使用圖形、圖片或圖表強化特定概念。這張圖片的前後文字應說明圖片的內容為何。圖片應儲存在特定的「images/」目錄或通用的「images/」目錄中。您也應該將圖片的來源檔案儲存在「images/src/」目錄中。

良好的概念說明文件通常包含：

  • Description (而非指令)
  • 背景概念
  • 圖表或其他視覺輔助內容 (建議使用 .png 格式)
  • 程序和/或參考文件的連結

撰寫文件後，最好還是檢查文件、站在使用者的立場 (不再是開發功能的專家)，然後嘗試回答下列問題：

  • 這份文件中的資訊是否完整說明瞭這項概念？
  • 這個概念是否不需要提供任何資訊？如果是的話，請將其移除。
  • 關於背景功能可能的運作方式，是否有任何不必要的細節？
  • 如果我是使用者，還有其他需要知道的資訊嗎？

如果這些問題尚未獲得完整解答，請再次編輯文件。

參考說明文件

參考說明文件應提供系統部分的相關資訊，包括但不限於 API 和 CLI。就該類型的所有參考說明文件而言，參考說明文件的樣式應相同。舉例來說，API 說明文件應定義所有 API 的參數，指出參數為必要或選用，並顯示 API 的使用範例。這些範例應為通用且簡單。如果需要更詳細的範例，請考慮建立程序文件來強化參考說明文件。

如需 API 說明文件的樣式指南，請參閱 API 樣式指南。