本文件概述 Fuchsia 說明文件的標準、結構、語氣和最佳做法。
文件位置
- 特定 Fuchsia 功能開發專屬說明文件：提供給開發人員建立或維護 Fuchsia 程式碼集特定部分的說明文件，應與原始碼存放在同一目錄中。這些文件通常以
README.md檔案的形式嵌入整個 Fuchsia 程式碼集。 Fuchsia 開發人員一般說明文件：必須在
/HEAD/docs/中建立 Fuchsia 說明文件。在/docs/目錄中，您應在下列其中一個子目錄中建立說明文件：get-started：如需下載、設定及開始在 Fuchsia 上開發的詳細指南，請前往/docs/get-started。此內容應包含主題明確的簡短教學課程，可協助新使用者開始使用 Fuchsia，以及前往 Fuchsia.dev 的其他說明文件連結。development：/docs/development/目錄 (在網站上顯示為「指南」) 包含開發人員使用 Fuchsia 使用的操作說明和教學課程。這個目錄包含有關如何建構、執行及測試 Fuchsia 的說明文件。concepts：/docs/concepts目錄包含 Fuuchsia 特定功能和運作方式的深入說明，包括作業系統總覽、架構、架構和套件。reference：/docs/reference/目錄內含 Fuchsia 工具和 API 產生的參考文件，包括 FIDL 和核心參考資料。contribute：/docs/contribute/目錄包含程式碼和說明文件貢獻程序和最佳做法，包括說明文件程式碼和樣式指南、程式碼輪詢以及管理機制。images/docs/images/目錄包含說明文件中使用的圖片。您應將圖片放在這個通用目錄中。
文件類型
大多數的說明文件可分為以下類別：
- 程序
- 開始使用：初始設定說明文件
- 指南 - 工作導向的說明文件
- 概念 - 著重說明 Fuchsia、Fuchsia 架構和 Fuchsia 元件的基本說明文件
- 參考資料 - 說明文件著重在詳細介紹 Fuchsia API 和工具的語法和參數。這份說明文件通常由系統自動產生。
詳情請參閱「說明文件類型」。
說明文件和程式碼樣式指南
請務必遵循說明文件樣式規範，確保大量協作者建立的說明文件保持一致。如需具體說明文件指南，請參閱「說明文件樣式指南」；如需程式碼範例，請參閱「程式碼範例樣式指南」。
搜尋最佳做法
使用者必須能找到說明文件，說明文件才能派上用場。以下列舉部分尋找度和搜尋的最佳做法：
- 將您的文件新增至目錄：在 fuchsia.dev 的左側導覽中新增說明文件連結。詳情請參閱「網站導覽和 TOC 檔案」一文。
- 交叉連結說明文件：新增主題的文件連結，協助讀者進一步瞭解文件內容。舉例來說，Fuchsia 模擬器的概念文件會連結至相關指南和 Fuchsia 模擬器的入門指南。
- 使用一致的術語：當您撰寫 Fuchsia 中的特定概念時，請確認您使用一致的術語。請使用詞彙解釋驗證字詞。
說明文件檔案格式和檔案名稱
Fuchsia 的所有說明文件皆以 Markdown (.md) 編寫，而 Fuchsia.dev 使用 Hoedown Markdown 剖析器。
網站的導覽功能是由 _toc.yaml 檔案設定，這些檔案包含在每個說明文件目錄中。請按照網站導覽與 TOC 檔案中的指南更新這些檔案。
檔案和目錄名稱必須為小寫，並以連字號分隔字詞，而非底線。檔案和目錄名稱只能使用標準 ASCII 英數字元，如果檔案名稱包含有底線的指令，您可以加上底線。
風格和語氣的一般指南
以簡單的美國英文撰寫內容。用英文寫出清楚的英文 (美國) 語言，讓內容更容易理解。使用簡單的字詞、簡單扼要，並使用「它」或「不要」等縮寫字詞。
保持尊重。請遵循尊重程式碼中提出的規定。
撰寫第二人稱「您」。Fuchsia 說明文件為使用者 (簡稱「您」) 寫入。例如：「您可以執行下列動作安裝 Fuchsia...」。請勿提及第三人稱的讀卡機 (「Fuchsia 使用者可以用...安裝 Fuchsia」)，或使用「We」(「我們可安裝 Fuchsia 的依據...」)。
寫下目前時態。請務必按照原樣來記錄系統，切勿依現狀。「will」之類的字詞會不太明確。舉例來說，「您會看到」還剩 1 分鐘還是 20 分鐘？此外，除非必要，否則請勿提及日後的產品功能。提及可能無法達成的未來計畫將成為維護負擔。
句子應簡短扼要。使用標點符號可讓讀者遵循指示並瞭解概念。此外，短句可以協助翻譯。
瞭解觀眾。請先定義目標對象，再撰寫文件。瞭解目標對象能讓你瞭解觀眾應該熟悉哪些資訊。如果文件適用於更進階的目標對象，請事先說明文件的必要條件，然後再閱讀文件。
使用主動語態。盡量使用主動語態，因為被動語態可能會讓句子產生模糊不清且難以理解。範例如下：
- 主動語態：「作業系統會執行程序。」在本例中，主詞會執行動詞表示的動作。
- 被動語態：「執行處理程序。」主詞不再是 active，而是動詞的上移，也就是「被動」。在多數情況下，如果使用「by」，表示您的句子可能仍然是被動語態。
如要使用縮寫詞，請在第一次撰寫提及時定義。例如，看起來沒問題 (LGTM)。請不要假設每個人都一定能理解所有縮寫的縮寫。您不需要定義符合業界標準的縮寫，例如 TCP/IP。
定義技術術語並避免專業術語。所有層級的開發人員都應能存取 Fuchsia 說明文件。請避免使用不常見或高度技術用詞的過度說明文件。如果您要使用 Fuchsia 專用字詞，請在詞彙表中定義這些字詞。避免使用發明字詞。
避免使用口語或區域的慣用語。請注意，許多 Fuchsia 使用者 可能不是英文使用者請避免難以翻譯的慣用語，例如 「這是 Cookie 的破壞方式」。雖然這有可能符合您的需求，但可能無法翻譯成其他語言。
避免參照專屬資訊。這可能指任何可能註冊商標的術語或產品名稱，或公司內部的任何內部資訊 (API 金鑰、裝置名稱等)。
使用中性代名詞。請勿使用「他、他、他的、她的、她或她」，也不要使用「他」、「他」或其他這類標點符號方式。請改用單數選項。
使用一致的術語。確保程式碼、UI 和說明文件中的字詞一致。盡可能使用常見詞彙，並使用詞彙解釋確認術語。