感謝您為 Bazel 的說明文件做出貢獻。這份文件可做為快速文件樣式指南，協助您快速上手。如果您對這份指南未回答的格式問題有任何疑問，請參閱 Google 開發人員說明文件格式指南。
定義原則
Bazel 文件應遵循下列原則：
- 精簡。文字越精簡越好。
- 清晰。使用平實的語言。以五年級的閱讀程度撰寫，避免使用專業術語。
- 一致性。在文件中重複使用相同的字詞或詞組來表示概念。
- 答對了！避免使用以時間為準的資訊和承諾，讓內容盡可能保持正確。
寫作
本節提供基本寫作訣竅。
標題
- 頁面層級標題從 H2 開始。(H1 標題可做為網頁標題)。
請盡可能簡短標題。這樣一來，這些項目就會適合放入 TOC 中，而不需要換行。
- 是：權限
- 否：簡短的權限說明
使用句首字母大寫格式
- 是：設定工作區
- 否：設定工作區
試著讓標題以工作為主或可做為行動依據。如果標題具有概念，則或許該著眼於使用者的理解，但應以使用者的敘述方式撰寫。
- 是：保留圖表順序
- 否：保留圖表順序
名稱
請使用正確的名詞，例如 Bazel 和 Starlark。
- 是：在建構作業結束時，Bazel 會列印要求的目標。
- 否：在建構結束時，bazel 會顯示要求的目標。
請確保類型前後一致。請勿為現有概念導入新名稱。在適用情況下，請使用專有名詞詞彙表中定義的字詞。
- 舉例來說，如果您要撰寫關於在終端機上發出指令的內容，請勿在頁面上同時使用終端機和指令列。
網頁範圍
每個頁面都應有一個用途，且應在開始時定義。這有助讀者更快找到所需內容。
- 是：本頁面說明如何在 Windows 上安裝 Bazel。
- 否：(沒有開頭句子)。
在頁面結尾告訴讀者接下來該做什麼。如果網頁沒有明確的動作，您可以加入連結，連往類似概念、範例或其他探索途徑。
主旨
在 Bazel 說明文件中，目標對象應該主要是使用者，也就是使用 Bazel 建構軟體的人。
請以「你」稱呼讀者。(如果您因某些原因無法使用「您」，請使用性別中立的用詞，例如「他們」)。
- 是：如要使用 Bazel 建構 Java 程式碼，您必須安裝 JDK。
- MAYBE：使用者必須安裝 JDK，才能使用 Bazel 建構 Java 程式碼。
- 否：使用者必須安裝 JDK，才能使用 Bazel 建構 Java 程式碼。
如果目標對象並非一般 Bazel 使用者，請在頁面開頭或專區中定義目標對象。其他目標對象可包括維護者、貢獻者、遷移者或其他角色。
避免使用「我們」一詞。在使用者文件中，沒有作者；請直接告訴使用者可能發生的情況。
- 是：隨著 Bazel 的演進，您應更新程式碼集以維持相容性。
- 否：Bazel 仍在不斷改進，我們會對 Bazel 進行變更，但有時會造成不相容的情形，因此 Bazel 使用者需要進行一些變更。
時間
盡可能避免使用會讓人聯想到時間的字詞，例如提及特定日期 (2022 年第 2 季)，或使用「現在」、「目前」或「即將」等字詞。這些資料很快就會過時，如果是未來的預測資料，可能會不正確。請改為指定版本等級，例如「Bazel X.x 以上版本支援 <功能>」或 GitHub 問題連結。
- 是：Bazel 0.10.0 以上版本支援遠端快取。
- 否：Bazel 即將支援遠端快取功能，預計於 2017 年 10 月推出。
緊張
使用現在式。除非為了清楚表達而必須使用，否則請避免使用過去或未來時態。
- 是：Bazel 會在發現不符合此規則的依附元件時發出錯誤。
- 否：如果 Bazel 發現不符合此規則的依附元件，就會發出錯誤。
請盡可能使用主動語音 (主體對物件執行動作) 使用非被動語態 (由主體執行動作)。一般來說，主動語態可讓句子更清楚，因為它會指出誰負責。如果使用主動語態會影響清楚度，請改用被動語態。
- 是：Bazel 會啟動 X，並使用輸出內容建構 Y。
- 否：X 是由 Bazel 啟動，之後 Y 會使用輸出內容建構。
語氣
以親切的商業語氣撰寫。
避免使用口語化的用語。英文特有的詞組會較難翻譯。
- 是：良好的規則集
- 否：那麼什麼是良好的規則集？
避免使用過於正式的用語。撰寫時，請假設你要向對科技感興趣但不瞭解細節的人解釋概念。
格式設定
檔案類型
為提高可讀性，請將每行字元數限制在 80 個半形字元。長連結或程式碼片段可以更長，但應從新行開始。例如：
連結
請使用說明性連結文字，不要使用「這裡」或「下方」。這樣一來，使用者就能更輕鬆地掃描文件，螢幕閱讀器也能更順暢地運作。
- 是：詳情請參閱 [安裝 Bazel]。
- 否：詳情請參閱 [這裡]。
盡可能在句尾加上連結。
- 是：詳情請參閱 [link]。
- 否：詳情請參閱 [連結]。
清單
- 使用已排序清單說明如何完成含有步驟的工作
- 使用無序清單列出非工作相關的項目。(但仍應有排序順序，例如字母順序、重要性等)。
- 使用平行結構書寫。例如：
- 將所有清單項目轉為句子。
- 先使用相同時態的動詞。
- 如有步驟，請使用已排序的清單。
預留位置
並使用角括號表示使用者應變更的變數。在 Markdown 中，請使用反斜線逸出尖括號：
\<example\>。- 是：
bazel help <command>：列印<command>的說明和選項 - 否：bazel help 指令：列印「指令」的說明和選項
- 是：
尤其是在複雜的程式碼範例中，請使用在上下文中合理的預留位置。
目錄
使用網站支援的自動產生目錄。請勿手動新增目錄。
程式碼
程式碼範例是開發人員的好幫手。您可能已經知道如何編寫這些內容，但以下提供一些訣竅。
如果您要參照一小段程式碼，可以將該程式碼嵌入句子中。如果您希望讀者使用程式碼 (例如複製指令)，請使用程式碼區塊。
程式碼區塊
- 保持簡短扼要。從程式碼範例中移除所有多餘或不必要的文字。
- 在 Markdown 中加入範例語言，即可指定程式碼區塊類型。
```shell
...
- 將指令和輸出內容分隔成不同的程式碼區塊。
內嵌程式碼格式
- 請為檔案名稱、目錄、路徑和小段程式碼使用程式碼樣式。
- 使用內嵌程式碼樣式，而非斜體、"引號"或bolding。
- 是：
bazel help <command>：列印<command>的說明和選項 - 否：bazel help 指令：列印「指令」的說明和選項
- 是：