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