感謝您為 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]」。
- 否:詳情請參閱 [這裡]。
盡可能在句尾加上連結。
- 是:詳情請參閱 [連結]。
- 否:詳情請參閱 [連結]。
清單
- 使用有順序的清單,說明如何完成任務的步驟
- 使用無序清單列出非工作相關的項目。(但仍應有排序順序,例如字母順序、重要性等)。
- 使用平行結構書寫。例如:
- 將所有清單項目轉為句子。
- 請先從同樣時態的動詞開始。
- 如果有步驟可遵循,請使用排序清單。
預留位置
使用尖括號表示使用者應變更的變數。在 Markdown 中,請使用反斜線逸出尖括號:
\<example\>
。- 是:
bazel help <command>
:列印<command>
的說明和選項 - 否:bazel help 指令:列印「指令」的說明和選項
- 是:
尤其是在複雜的程式碼範例中,請使用在上下文中合理的預留位置。
目錄
使用網站支援的自動產生目錄。請勿手動新增目錄。
程式碼
程式碼範例是開發人員的好幫手。您可能已經知道如何編寫這些內容,但以下提供一些訣竅。
如果您要參照一小段程式碼,可以將該程式碼嵌入句子中。如果您希望讀者使用程式碼 (例如複製指令),請使用程式碼區塊。
程式碼區塊
- 保持簡短扼要。從程式碼範例中移除所有多餘或不必要的文字。
- 在 Markdown 中,請新增範例的語言,指定程式碼區塊類型。
```shell
...
- 將指令和輸出內容分隔成不同的程式碼區塊。
內嵌程式碼格式
- 請為檔案名稱、目錄、路徑和小段程式碼使用程式碼樣式。
- 使用內嵌程式碼樣式,而非斜體、"引號"或加粗。
- 是:
bazel help <command>
:列印<command>
的說明和選項 - 否:bazel help 指令:列印「指令」的說明和選項
- 是: