感謝您為 Bazel 文件貢獻一己之力。這份快速說明文件樣式指南可協助您快速上手。如有本指南未回答的任何樣式問題，請按照 Google 開發人員說明文件樣式指南進行操作。
定義原則
Bazel 文件應維持以下原則：
- 精簡。盡量減少字數，
- 清除。使用純文字。提供五年級的閱讀程度，無需書寫語言。
- 一致。在整個文件中重複使用相同字詞或詞組。
- 正確。請盡可能避免且以時間為依據的資訊，並保證未來發展。
寫作
這個部分包含基本的寫作提示。
標題
- 網頁層級標題是從 H2 開始。(使用 H1 標題做為網頁標題)。
使用精簡的標題。如此一來，這些工具就不用納入包裝
- 是：權限
- 否：權限的注意事項
標題使用句首字母大寫格式
- 是：設定工作區
- 否：設定工作區
嘗試將標題設為以工作為基礎的，或做為可行動作。如果標題是概念概念，則可能是基於理解考量，但要寫入使用者的操作內容。
- 是：保留圖表順序
- 否：在保留圖表順序時
名稱
將適當名詞大寫，例如 Bazel 和 Starlark。
- 是：建構完成後，Bazel 會列印要求的目標。
- 否：在建構作業結束時，Bazel 會輸出要求的目標。
請確保類型前後一致。請勿為現有概念推出新名稱。在適用情況下，請使用詞彙表中定義的字詞。
- 例如，如果您要在終端撰寫指令，請不要使用網頁上的終端機和指令列。
頁面範圍
每個網頁應該都有一個特定用途，它應該一開始就應該定義。這可幫助讀者更快找到所需內容。
- 是：本頁面介紹如何在 Windows 上安裝 Bazel。
- 否：(沒有介紹句子)。
在頁面最後，告訴讀者接下來該怎麼做。如果網頁沒有明確動作，您可以加入類似概念、範例或其他探索途徑的連結。
主旨
在 Bazel 說明文件中，目標對象應為使用者，也就是使用 Bazel 建構軟體的使用者。
將讀者稱為「你」。(如果因為某些原因無法使用「您」，請使用性別中立語言，例如這些語言)。
- 是：如要使用 Bazel 建構 Java 程式碼，您必須安裝 JDK。
- MAYBE：如要讓使用者透過 Bazel 建構 Java 程式碼，則必須安裝 JDK。
- 否：使用者必須安裝 JDK，才能使用 Bazel 建構 Java 程式碼。
如果您的目標對象「不是」一般 Bazel 使用者，請在網頁開始或區段中定義目標對象。其他目標對象可以包含維護者、協作者、遷移員或其他角色。
避免使用「我們」。使用使用者文件沒有作者，只要告訴使用者可行性。
- 是：當 Bazel 不斷演進，您應該更新程式碼集以維持相容性。
- 否：Bazel 會不斷改變，因此我們會進行 Bazel 變更，不時會導致不相容的情況，因此需要 Bazel 使用者進行一些變更。
時間
請盡量避免呈現符合時事的術語，例如參照特定日期 (2022 年第 2 季) 或說出「現在」、「目前」或「即將」。這些資訊會迅速更新，如果日後的預測出現錯誤，就會造成錯誤。請改為指定版本層級，例如「Bazel X.x 以上版本支援 <feature>」或 GitHub 問題連結。
- 是：Bazel 0.10.0 以上版本支援遠端快取。
- 否：Bazel 將於 2017 年 10 月開始支援遠端快取功能。
緊張
使用時態。除非絕對必要，否則請避免使用過去或未來的時態。
- 是：Bazel 會找出不符合此規則的依附元件。
- 否：如果 Bazel 發現不符合這項規則的依附元件，就會發出錯誤。
請盡可能使用主動語氣 (物件在物件上時) 而非被動語態 (物件由對端執行的動作)。一般而言，主動語態可讓語句更清晰，因為這個詞顯示誰負責。如果使用中的語音對清晰度造成乾擾，請使用被動語音。
- 是：Bazel 會啟動 X 並使用輸出內容建構 Y。
- 否：X 由 Bazel 啟動，之後將使用輸出內容建立 Y。
內容基調
用友善的口氣創作內容。
避免使用口語的語句。翻譯英文專用的詞組較難翻譯。
- 是：規則良好
- 否：設定良好的規則組合有哪些？
避免使用過度正式的語言。請描述自己對於某個技術好奇且不瞭解這些細節的概念。
格式設定
檔案類型
為方便閱讀，請用 80 個字元換行。長的連結或程式碼片段或許較長，但應以新一行開始。例如：
連結
使用描述性連結文字，而不是「在此」或「下方」。這種做法可簡化文件掃描作業，並有助於螢幕閱讀器使用。
- 是：詳情請參閱 [安裝 Bazel]。
- 否：詳情請參閱 [這裡]。
如果可以的話，請在結尾加上連結。
- 是：詳情請參閱 [link]。
- 否：詳情請參閱 [link]。
清單
- 使用有序清單說明如何完成步驟
- 使用未排序的清單，列出不是以任務為基礎的項目。(應用程式仍應該依照字母順序、重要性等順序排列)。
- 以平行結構編寫。例如：
- 將清單項目中的所有句子設為句子。
- 以相同時態的動詞開始。
- 如果有需要完成的步驟，請使用已排序的清單。
預留位置
使用角括號表示使用者應變更的變數。 在 Markdown 中，使用反斜線逸出角括號：
\<example\>。- 是：
bazel help <command>：列印<command>的說明和選項 - No：bazel help command：列印「Command」的說明說明和選項
- 是：
尤其對複雜的程式碼範例而言，請使用符合情境的預留位置。
目錄
請使用網站支援的自動產生的 TOC。請勿新增手動 TOC。
程式碼
程式碼範例是開發人員的最佳好友。您可能已經知道如何編寫這些程式碼，但以下提供一些訣竅。
如果你要參照一小段程式碼，可以將其嵌入在句子中。 如要讓讀取者使用程式碼 (例如複製指令)，請使用程式碼區塊。
程式碼區塊
- 保持簡短扼要。從程式碼範例中移除所有多餘或不必要的文字。
- 在 Markdown 中，新增範例語言即可指定程式碼區塊的類型。
```shell
...
- 將指令分隔為不同的程式碼區塊。
內嵌程式碼格式設定
- 檔案名稱、目錄、路徑以及一小段程式碼使用程式碼樣式。
- 使用內嵌程式碼樣式，不要使用斜體、「引號」或粗體。
- 是：
bazel help <command>：列印<command>的說明和選項 - No：bazel help command：列印「Command」的說明說明和選項
- 是：