格式指南

目錄

標題和副標題

讀者會稍微多注意標題、項目符號清單和連結，因此務必確保這些項目中的前兩個到三個字盡可能地「預先載入」資訊。

最佳實務

  • 標題和副標題應讓讀者知道他們將在頁面上找到什麼內容。
  • 它們應該簡潔準確地描述內容的主題。
  • 標題應簡短（不超過八個字）、切中要點，並以簡潔、主動的語言撰寫。
  • 您應該避免使用雙關語、引人好奇的語句和文化參考。
  • 省略開頭的冠詞（例如「一個」、「這個」等）

頁面標題

頁面標題應以行動為導向。例如： - *啟用 SCIM* - *安裝 Docker Desktop*

最佳實務

  • 確保您的頁面標題和目錄 (TOC) 項目相符。
  • 如果您想在目錄 (_toc.yaml) 中的頁面標題使用「:」，則必須將整個標題用「」括起來，以免導致建置失敗。
  • 如果您在 TOC 檔案中新增一個新項目，請確保它以斜線 (/) 結尾。否則，頁面將不會顯示側邊導覽列。

圖片

圖片（包括螢幕截圖）可以幫助讀者更好地理解概念。但是，您應該謹慎使用它們，因為它們容易過時。

最佳實務

  • 當您截取螢幕畫面時
    • 不要使用 lorem ipsum 文字。嘗試複製使用者在實際情況下如何使用該功能，並使用實際的文字。
    • 僅擷取相關的 UI。不要包含不必要的空白區域或無助於說明重點的 UI 區域。
    • 保持小巧。如果您不需要顯示螢幕的完整寬度，就不要顯示。
    • 檢查圖片在頁面上的顯示方式。確保圖片不會模糊或過大。
    • 保持一致性。協調螢幕截圖與文件頁面上已有的其他螢幕截圖，以提供一致的閱讀體驗。
    • 為了保持 Git 儲存庫的輕量級，請（無損地）壓縮圖片。請務必在將圖片新增到儲存庫之前壓縮它們。在將圖片新增到儲存庫後再壓縮它們實際上會加劇對 Git 儲存庫的影響（但是，它仍然可以最佳化瀏覽期間的頻寬）。
    • 不要忘記從儲存庫中移除不再使用的圖片。

有關如何將圖片新增到內容的資訊，請參閱實用組件和格式範例。

小心不要建立過多連結，尤其是在正文中。過多的連結可能會分散讀者的注意力或將讀者引離當前頁面。

當人們點擊連結時，他們常常會失去思路，無法返回原始頁面，儘管他們尚未吸收所有資訊。

最佳連結可為讀者提供另一種瀏覽資訊的方式。

最佳實務

  • 使用不會誤導或過度承諾的簡潔語言。
  • 簡短且具描述性（大約五個字最好）。
  • 允許人們（相當有把握地) 預測如果他們選擇連結將會得到什麼。盡可能在連結中反映目標頁面上的標題文字。
  • 將以使用者和動作為導向的詞彙放在連結的開頭（例如「下載我們的應用程式」）。
  • 避免使用通用的行動呼籲（例如「點擊此處」、「了解更多」）。
  • 當您建立文字超連結時，不要包含任何結尾標點符號（例如句點、問號或驚嘆號）。
  • 不要將連結文字設定為斜體或粗體，除非它在一般正文中也是如此。

有關如何將連結新增到內容的資訊，請參閱實用組件和格式範例。

程式碼和程式碼範例

將以下內容格式化為程式碼：Docker 指令、說明和檔案名稱（套件名稱）。

要套用內嵌程式碼樣式，請將文字用單個反引號 (`) 括起來。

有關如何將程式碼區塊新增到內容的資訊，請參閱實用組件和格式範例。

指令最佳實務

  • 命令提示字元和 Shell
    • 對於非特權 Shell，在程式碼區塊中以 $ 提示符號作為指令的前綴。
    • 對於特權 Shell，在程式碼區塊中以 # 提示符號作為指令的前綴。
    • 對於遠端 Shell，新增遠端機器的上下文，並排除路徑。例如，`user@host $`。
    • 當您新增任何 Windows 特定指令時，請指定 Windows Shell（命令提示字元、PowerShell 或 Git Bash）。不需要為每個 Windows Shell 都包含一個指令。
    • 當您為多個作業系統或 Shell 新增指令時，請使用索引標籤。有關如何將索引標籤新增到內容的資訊，請參閱索引標籤。
  • 使用者將複製並執行的指令
    • 如果指令會產生輸出或需要使用者驗證結果，請在每個程式碼區塊中新增一個指令。
    • 將指令輸出新增到與指令不同的程式碼區塊中。
  • 使用者不會複製和執行的指令
    • 使用 POSIX 相容的語法。不需要包含 Windows 語法。
    • 將選用引數用方括號（[ ]）括起來。
    • 在互斥的引數之間使用管道符號（|）。
    • 在重複的引數後使用三個點（...）。

程式碼最佳實務

  • 當您將程式碼區塊嵌套在清單項目下時，請將程式碼區塊縮排 3 個空格。
  • 當您省略程式碼時，請使用三個點（...）。

註解框

使用註解框來強調頁面上的選定資訊。

最佳實務

  • 將「警告」、「重要」或「備註」等字詞格式化為粗體。不要將註解框內的內容設為粗體。
  • 最佳做法是避免在一個頁面上放置大量文字註解框。如果過度使用，它們會造成頁面雜亂，而且會降低其影響力。
文字註解框使用案例情境顏色或註解框
警告使用「警告」標籤向讀者發出訊號，指示哪些動作可能會導致硬體損壞或軟體資料遺失。紅色
✅ 範例：警告：當您使用 docker login 指令時，您的憑證會儲存在您的家目錄中的 .docker/config.json 中。密碼會在此檔案中以 base64 編碼。
重要使用「重要」標籤向讀者發出訊號，指示哪些動作可能會導致較小程度的問題。黃色
✅ 範例：更新 Docker Desktop 條款
備註使用「備註」標籤提供可能不適用於所有讀者的資訊，或者如果資訊與主題不直接相關。藍色
✅ 範例：刪除儲存庫會刪除它包含的所有映像及其建置設定。此動作無法復原。

有關如何將註解框新增到內容的資訊，請參閱實用組件和格式範例。

記錄如何在 Docker Desktop 或 Docker Hub UI 中導覽時

  • 一律先說明位置，再說明動作。例如：*從**可見度**下拉式清單（位置）中，選擇**公開**（動作）。*
  • 簡潔具體。例如：應該：*選擇**儲存**。* 不應該：*選擇**儲存**以使變更生效。*
  • 如果步驟必須包含原因，請以原因開始步驟。這有助於使用者更快地瀏覽。應該：*若要檢視變更，請在合併請求中選擇連結。* 不應該：*選擇合併請求中的連結以檢視變更*

選用步驟

如果步驟是選用的，請以「選用」一詞加上句點開始步驟。

例如

1. 選用。輸入作業的描述。

預留位置文字

您可能想要提供使用特定值的指令或設定。

在這些情況下，使用 < 和 > 來標示讀者必須用自己的值替換文字的位置。例如

docker extension install <您的擴充功能名稱>

表格

使用表格以簡潔的方式描述複雜的資訊。

請注意，在許多情況下，使用未排序的清單就足以描述每個項目都只有一個簡單描述的項目清單。但是，如果您有最適合用矩陣描述的資料，則表格是最佳選擇。

最佳實務

  • 表格標題使用句子大小寫。
  • 為了保持表格的可存取性和可瀏覽性，表格中不應有任何空的儲存格。如果儲存格沒有其他有意義的值，請考慮輸入「N/A」（表示「不適用」）或「無」。

有關如何將表格新增到內容的資訊，請參閱實用組件和格式範例。

引用檔案類型

當您討論檔案類型時，請使用該類型的正式名稱。不要使用副檔名來泛指檔案類型。

| Correct | Incorrect |
| --- | --- |
| a PNG file | a .png file |
| a Bash file | an .sh file |

引用單位

當您參考度量單位時，請使用全大寫的縮寫形式，並在數值和單位之間留一個空格。例如：

| Correct | Incorrect |
| --- | --- |
| 10 GB | 10GB |
| 10 GB | 10 gb |
| 10 GB | 10 gigabytes |