感謝您參與 Bazel 說明文件。這份快速說明文件樣式指南可幫助您快速上手。關於本指南未解答的任何樣式問題，請參閱 Google 開發人員說明文件樣式指南。
定義原則
Bazel 文件應遵循以下原則：
- 精簡扼要。用字越少越好。
- 清晰。使用淺顯易懂的用語。為五年級的閱讀級別編寫，無須使用術語。
- 穩定一致：請使用相同字詞或詞組，在整個文件中使用重複的概念。
- 答對了。避免以時間為準的資訊並做出未來承諾，盡可能讓內容保持正確性。
寫作
本章節包含基本的寫作提示。
標題
- 網頁層級標題從 H2 開始。(H1 標題則是網頁標題)。
盡可能縮短標頭。這樣一來，這些容器就能直接融入 TOC，不會換行。
- 是：權限
- 否：關於權限的簡短注意事項
採用句首字母大寫標題
- 是：設定工作區
- 否：設定工作區
因此，標題應設計以工作為導向，或是能做為行動依據。如果標題屬於概念性質，可能是依據對使用者的理解，而是寫入使用者的行為。
- 是：保留圖表順序
- 否：系統會保留圖表順序
名稱
請使用 Bazel 和 Starlark 等專有名詞大寫。
- 是：當建構作業結束時，Bazel 會顯示要求的目標。
- No：建構結束時，Bazel 會顯示要求的目標。
保持一致。不要為現有概念引進新名稱，在適用情況下，請使用詞彙表中定義的字詞。
- 舉例來說，假設您是在終端機發出指令，請勿在頁面上同時使用終端機和指令列。
頁面範圍
每個頁面都應有一項用途，且應於開頭定義。讓讀者可以更快找到所需資訊。
- 是：本頁面說明如何在 Windows 上安裝 Bazel。
- 否：(沒有引言語句)。
在頁面結尾處告知讀者接下來該採取什麼行動。對於沒有明確操作的網頁，您可以加入類似概念、範例或其他探索管道的連結。
主旨
在 Bazel 說明文件中，目標對象主要應為使用者，也就是使用 Bazel 建構軟體的人員。
將讀者稱作「你」。(如果因故無法使用「您」，請使用性別中立的語言，例如這些語言)。
- 是：如要使用 Bazel 建構 Java 程式碼，您必須安裝 JDK。
- MAYBE：如果使用者要使用 Bazel 建構 Java 程式碼，就必須安裝 JDK。
- 否：當使用者想利用 Bazel 建構 Java 程式碼時，必須安裝 JDK。
如果您的目標對象「不是」一般的 Bazel 使用者，請在頁面開頭或這個部分定義目標對象。其他目標對象可以是維護者、貢獻者、遷移者或其他角色。
別說「我們」，使用者文件中沒有作者，只告訴其他人可以開發什麼內容。
- 是：隨著 Bazel 不斷演進，您應更新程式碼集以維持相容性。
- 否：Bazel 仍在持續發展中，因此我們會視情況對 Bazel 進行變更，日後將不相容，而且 Bazel 使用者可能需要進行變更。
時間
請盡可能避免使用與時序相關的字詞，例如參照特定日期 (2022 年第 2 季)，或是說出「現在」、「目前」或「即將」。這些錯誤很快就會過時，如果之後是投影，可能會不正確。請改為指定版本層級，例如「Bazel X.x 以上版本支援 <feature> 或 GitHub 問題連結。
- 是：Bazel 0.10.0 以上版本支援遠端快取。
- 否：Bazel 即將支援遠端快取 (可能於 2017 年 10 月)。
緊張
使用目前時態。除非絕對必要，否則請避免使用過去或未來的時態。
- 是：Bazel 發現任何不符合這項規則的依附元件時會回報錯誤。
- 否：如果 Bazel 發現依附元件不符合這項規則，Bazel 就會發生錯誤。
盡可能使用主動語態 (主體對物體施行) 而非被動語態 (也就是主體的動作)。一般來說，主動語態會讓句子顯得負責者，使句子更清楚。如果使用主動語態會使清晰度降低，請使用被動語態。
- 是：Bazel 會啟動 X，並使用輸出內容建構 Y。
- 否：X 是由 Bazel 啟動，之後 Y 將用來建構該輸出內容。
語氣
以適合企業的語氣撰寫內容。
避免使用口語用法。很難翻譯英文的特殊詞組。
- 是：良好規則集
- 否：什麼是良好的規則集？
避免使用過於正式的語言。就像要解釋這個概念，一般人會想著科技，卻不知道技術細節。
格式設定
檔案類型
為了方便閱讀，請以 80 個字元換行。長連結或程式碼片段可能比較長，但每行只能輸入一個內容。例如：
連結
使用說明連結文字，不要使用「這個頁面」或「以下」部分。這個做法有助於更輕鬆地掃描文件，而且較適合螢幕閱讀器。
- 是：詳情請參閱 [安裝 Bazel]。
- 否：詳情請參閱 [這裡]。
盡可能以連結結尾。
- 是：詳情請參閱 [link]。
- 否：詳情請參閱 [link]。
清單
- 使用已排序的清單，說明如何透過步驟完成工作
- 使用未排序的清單列出非任務型項目。(仍然是按照字母、重要性等排列順序)。
- 使用平行結構編寫。例如：
- 讓所有清單項目語句。
- 先使用時態相同的動詞。
- 如果有需要完成的步驟，請使用已排序清單。
預留位置
使用角括號表示使用者應變更的變數。在 Markdown 中，使用反斜線逸出角括號：
\<example\>。- 是：
bazel help <command>：列印<command>的說明和選項 - 否：bazel 說明指令：列印「指令」的說明和選項
- 是：
特別是對於複雜的程式碼範例，使用有意義的預留位置。
目錄
使用網站支援的自動產生 TOC。請勿手動新增 TOC。
程式碼
程式碼範例是開發人員的最佳夥伴。您或許已經知道如何編寫這些內容 這裡有一些秘訣
如要參照一小段程式碼，可以將程式碼嵌入句子中。如要讓讀取器使用程式碼 (例如複製指令)，請使用程式碼區塊。
程式碼區塊
- 保持簡短扼要。移除程式碼範例中所有多餘或不必要的文字。
- 在 Markdown 中，新增範例語言來指定程式碼區塊的類型。
```shell
...
- 將指令和輸出內容分成不同的程式碼區塊。
內嵌程式碼格式設定
- 針對檔案名稱、目錄、路徑和小部分程式碼使用程式碼樣式。
- 請使用內嵌程式碼樣式，不要使用斜體、「引號」或粗體。
- 是：
bazel help <command>：列印<command>的說明和選項 - 否：bazel 說明指令：列印「指令」的說明和選項
- 是：