Bazel 文件樣式指南

回報問題 查看原始碼 Nightly · 8.0 . 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

感謝您為 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]」。
    • :詳情請參閱 [這裡]。
  • 盡可能在句尾加上連結。

    • :詳情請參閱 [連結]。
    • :詳情請參閱 [連結]。

清單

  • 使用有順序的清單,說明如何完成任務的步驟
  • 使用無序清單列出非工作相關的項目。(但仍應有排序順序,例如字母順序、重要性等)。
  • 使用平行結構書寫。例如:
    1. 將所有清單項目轉為句子。
    2. 請先從同樣時態的動詞開始。
    3. 如果有步驟可遵循,請使用排序清單。

預留位置

  • 使用尖括號表示使用者應變更的變數。在 Markdown 中,請使用反斜線逸出尖括號:\<example\>

    • bazel help <command>:列印 <command> 的說明和選項
    • :bazel help 指令:列印「指令」的說明和選項
  • 尤其是在複雜的程式碼範例中,請使用在上下文中合理的預留位置。

目錄

使用網站支援的自動產生目錄。請勿手動新增目錄。

程式碼

程式碼範例是開發人員的好幫手。您可能已經知道如何編寫這些內容,但以下提供一些訣竅。

如果您要參照一小段程式碼,可以將該程式碼嵌入句子中。如果您希望讀者使用程式碼 (例如複製指令),請使用程式碼區塊。

程式碼區塊

  • 保持簡短扼要。從程式碼範例中移除所有多餘或不必要的文字。
  • 在 Markdown 中,請新增範例的語言,指定程式碼區塊類型。
```shell
...
  • 將指令和輸出內容分隔成不同的程式碼區塊。

內嵌程式碼格式

  • 請為檔案名稱、目錄、路徑和小段程式碼使用程式碼樣式。
  • 使用內嵌程式碼樣式,而非斜體、"引號"或加粗
    • bazel help <command>:列印 <command> 的說明和選項
    • :bazel help 指令:列印「指令」的說明和選項