格式指南

目錄

標題和副標題

讀者會對標題、無序列表和連結給予更多關注，因此務必確保這些專案的前兩三個詞儘可能地“前置”資訊。

最佳實踐

  • 標題和副標題應讓讀者知道頁面中會提供什麼內容。
  • 它們應簡潔準確地描述內容的主題。
  • 標題應簡短（不超過八個詞），直擊要點，並使用簡單、主動的語言撰寫。
  • 應避免雙關語、誘導性內容和文化引用。
  • 跳過冠詞（a, the 等）

頁面標題

頁面標題應面向行動。例如：- 啟用 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 個空格。
  • 忽略程式碼時使用三個點 ( ... )。

標註

使用標註來強調頁面上的特定資訊。

最佳實踐

  • 將 Warning、Important 或 Note 這些詞語設為粗體。不要將標註內的內容設為粗體。
  • 最好避免在同一頁面上放置過多的文字標註。過度使用可能會使頁面顯得雜亂，並削弱其效果。
文字標註用例場景顏色或標註框
警告使用 Warning 標籤向讀者指示哪些操作可能導致硬體或軟體損壞、資料丟失。紅色
✅ 示例：警告：使用 docker login 命令時，您的憑據會儲存在主目錄的 .docker/config.json 檔案中。密碼在此檔案中經過 base64 編碼。
重要使用 Important 標籤向讀者指示哪些操作可能導致程度較低的問題。黃色
✅ 示例：更新 Docker Desktop 條款
注意使用 Note 標籤用於可能不適用於所有讀者的資訊，或者資訊與主題相關但非核心。藍色
✅ 示例：刪除倉庫會刪除其中包含的所有映象及其構建設定。此操作無法撤銷。

關於如何向內容新增標註的資訊，請參閱有用的元件和格式化示例。

記錄如何透過 Docker Desktop 或 Docker Hub UI 進行導航時

  • 始終先說明位置，然後說明操作。例如：從可見性下拉列表（位置）中，選擇 Public（操作）。
  • 簡短且具體。例如：推薦：選擇儲存。 不推薦：選擇儲存使更改生效。
  • 如果步驟必須包含原因，請以原因開頭。這有助於使用者更快地掃描。推薦：要檢視更改，請在合併請求中選擇連結。 不推薦：選擇合併請求中的連結以檢視更改。

可選步驟

如果步驟是可選的，請以“可選.”（Optional.）開頭。

例如

1. 可選。輸入該作業的描述。

佔位符文字

您可能需要提供使用特定值的命令或配置。

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

docker extension install <name-of-your-extension>

表格

使用表格以直觀的方式描述複雜資訊。

注意，在許多情況下，無序列表足以描述每項具有簡單描述的列表。但是，如果資料最適合用矩陣描述，則表格是最佳選擇。

最佳實踐

  • 表格標題使用句子大小寫（即首字母大寫，其餘小寫）。
  • 為了使表格易於訪問和掃描，表格不應有空單元格。如果單元格沒有其他有意義的值，請考慮輸入 N/A（表示“不適用”）或 None。

關於如何向內容新增表格的資訊，請參閱有用的元件和格式化示例。

提及檔案型別

在討論檔案型別時，使用該型別的正式名稱。不要使用檔名副檔名泛指檔案型別。

| 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 |
頁面選項