感謝提供 Bazel 說明文件，這麼做可以快速 說明文件風格指南可幫助您快速上手。如有任何風格問題， 本指南所提供的解答，請按照 Google 開發人員說明文件樣式指南。
定義原則
Bazel 文件應堅守下列原則：
- 精簡扼要。文字越精簡越好。
- 清除。使用淺顯易懂的語言。輕鬆寫出五年級的專業術語 或讀物分級
- 穩定一致：使用相同的字詞或詞組來描述重複概念 整份文件
- 答對了！寫出能隨時保持內容正確性 並對未來發展做出承諾
寫作
本節提供基本的寫作提示。
標題
- 頁面層級標題會從下半年起開始。(H1 標題會用做網頁標題)。
請盡可能縮短標題。如此一來，這些物件就能融入 TOC 使用非換行符號
- 是：權限
- 否：有關權限的簡要注意事項
標題使用首字母大寫
- 是：設定工作區
- 否：設定工作區
試著讓標題以工作為主或可做為行動依據。如果標題具有概念 可能是基於理解的重點，但請寫下使用者的動作
- 是：保留圖表順序
- 否：保留圖表順序
名稱
請使用正確的名詞，例如 Bazel 和 Starlark。
- 是：Bazel 會在建構結束時輸出要求的目標。
- 否：在建構結束時，bazel 會顯示要求的目標。
保持一致。請勿為現有概念導入新名稱。地點 在適用情況下，請使用 詞彙解釋。
- 舉例來說，假設您要針對 終端機請勿在頁面中同時使用終端機和指令列。
頁面範圍
每個網頁都應有單一目的，而應在 自訂機器學習模型 但不想花時間從頭調整機器學習參數以便讀者更快找到所需內容。
- 是：本頁面說明如何在 Windows 上安裝 Bazel。
- 否：(無介紹語句)
在頁面結尾告訴讀者接下來該做什麼。如果是下列網頁： 沒有明確的行動，您可以加入類似概念的連結 或其他探索管道
主旨
在 Bazel 說明文件中，目標對象應該主要是使用者，也就是 使用 Bazel 建構軟體。
以「你」的身分稱呼讀者，(如果出於某些原因，無法使用「您」 使用中性用語，例如影片內容)。
- 是：如要使用 Bazel 建構 Java 程式碼， 您必須安裝 JDK
- 可能：如果使用者想使用 Bazel 建構 Java 程式碼，就必須安裝 JDK。
- 否：讓使用者使用 Bazel，他必須安裝 JDK。
如果您的目標對象「不會」一般 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 啟動，然後 之後則會依照輸出內容來建構。
語氣
撰寫內容時，請採用較商業友善的語氣，
避免使用口語化的用語。會較難翻譯 也很像英文
- 是：有效的規則集
- 否：那麼什麼是恰當的規則集？
避免使用過於正式的用語。撰寫時就像在說明 對科技迷感到好奇，但對技術一點並不瞭解的人。
格式設定
檔案類型
為了方便閱讀，請在 80 個字元處換行。長連結或程式碼片段 可能需要較長的時間，但應從頭開始。例如：
連結
使用描述連結文字，不要使用「此處」或「低於」這種做法 不僅簡化了文件掃描方式，也更適用於螢幕閱讀器。
- 是：詳情請參閱 [安裝 Bazel]。
- 否：詳情請參閱 [這裡]。
如果可以的話，請在句子結尾結束。
- 是：詳情請參閱 [link]。
- 錯誤：詳情請參閱 [link]。
清單
- 使用已排序清單說明如何完成含有步驟的工作
- 使用未排序的清單，列出非工作核心的項目。( 仍是排序順序，例如字母順序、重要性等)
- 以平行結構撰寫。例如：
- 將所有清單項目設為語句。
- 先使用相同時態的動詞。
- 如有步驟，請使用已排序的清單。
預留位置
使用角括號表示使用者應變更的變數。 在 Markdown 中，使用反斜線逸出角括號：
\<example\>。- 是：
bazel help <command>：沖印相片 「<command>」的說明和選項 - 否：Bazel 說明 command：列印說明 和「command」的選項
- 是：
特別是在複雜的程式碼範例中，請使用合理的預留位置 在使用上。
目錄
使用網站支援的自動產生的 TOC。請勿手動新增 TOC。
程式碼
程式碼範例是開發人員最要好的朋友您可能知道如何編寫這些程式碼 但以下提供幾點提示
如果參照的是一小段程式碼，則可以將其嵌入句子中。 如要讓讀取器使用程式碼 (例如複製指令)，請使用程式碼 封鎖。
程式碼區塊
- 保持簡短扼要。移除程式碼中所有多餘或不必要的文字 樣本。
- 在 Markdown 中加入範例語言，即可指定程式碼區塊類型。
```shell
...
- 將指令和輸出內容分隔為不同的程式碼區塊。
內嵌程式碼格式設定
- 使用程式碼樣式設定檔案名稱、目錄、路徑和一小段程式碼。
- 使用內嵌程式碼樣式，而非斜體、「引號」。或粗體文字。
- 是：
bazel help <command>：沖印相片 「<command>」的說明和選項 - 否：Bazel 說明 command：列印說明 和「command」的選項
- 是：