感謝提供 Bazel 說明文件，這提供了簡短的說明文件風格指南，協助您快速上手。針對本指南未回答的樣式問題，請參閱 Google 開發人員說明文件樣式指南。
定義原則
Bazel 文件應堅守下列原則：
- 精簡扼要。文字越精簡越好。
- 清除。使用淺顯易懂的語言。為五年級的閱讀程度撰寫不使用專業術語。
- 穩定一致：在整個文件中使用相同的字詞或詞組
- 答對了！撰寫時，請盡量避免提供時間性資訊，並對未來做出承諾，確保內容能夠隨時保持正確性。
寫作
本節提供基本的寫作提示。
標題
- 頁面層級標題會從下半年起開始。(H1 標題會用做網頁標題)。
請盡可能縮短標題。如此一來，這些物件就不會包裝在 TOC 中
- 是：權限
- 否：有關權限的簡要注意事項
標題使用首字母大寫
- 是：設定工作區
- 否：設定工作區
試著讓標題以工作為主或可做為行動依據。如果標題具有概念，則或許該著眼於使用者的理解，但應以使用者的敘述方式撰寫。
- 是：保留圖表順序
- 否：保留圖表順序
名稱
請使用正確的名詞，例如 Bazel 和 Starlark。
- 是：Bazel 會在建構結束時輸出要求的目標。
- 否：在建構結束時，bazel 會顯示要求的目標。
保持一致。請勿為現有概念導入新名稱。在適用情況下，請使用詞彙表中定義的字詞。
- 舉例來說，如果您要在終端機上發出指令，請勿在頁面中同時使用終端機和指令列。
頁面範圍
每個網頁都應該要有一個用途，而且必須在一開始時定義。以便讀者更快找到所需內容。
- 是：本頁面說明如何在 Windows 上安裝 Bazel。
- 否：(無介紹語句)
在頁面結尾告訴讀者接下來該做什麼。如果網頁沒有明確動作，您可以加入類似概念、範例或其他探索途徑的連結。
主旨
在 Bazel 說明文件中，目標對象應該主要是使用者，也就是使用 Bazel 建構軟體的人。
以「你」的身分稱呼讀者，(如果因故無法使用「您」，請使用中性用語，例如以性別表示)。
- 是：如要使用 Bazel 建構 Java 程式碼，您必須安裝 JDK。
- 可能：如果使用者想使用 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 說明 command：顯示「command」的說明和選項
- 是：
特別是在複雜的程式碼範例中，應使用符合情境的預留位置。
目錄
使用網站支援的自動產生的 TOC。請勿手動新增 TOC。
程式碼
程式碼範例是開發人員最好的朋友。您可能已經知道如何編寫這些內容
如果參照的是一小段程式碼，則可以將其嵌入語句中。 如要讓讀取器使用程式碼 (例如複製指令)，請使用程式碼區塊。
程式碼區塊
- 保持簡短扼要。清除程式碼範例中所有多餘或不必要的文字。
- 在 Markdown 中加入範例語言，即可指定程式碼區塊類型。
```shell
...
- 將指令和輸出內容分隔為不同的程式碼區塊。
內嵌程式碼格式設定
- 使用程式碼樣式設定檔案名稱、目錄、路徑和一小段程式碼。
- 請使用內嵌程式碼樣式，而不要使用斜體、「引號」或粗體。
- 是：
bazel help <command>：列印<command>的說明和選項 - 否：bazel 說明 command：顯示「command」的說明和選項
- 是：