格式化指南

目錄

標題和副標題

讀者對標題、專案符號列表和連結的關注度略高，因此務必確保這些專案的前兩到三個詞儘可能“前置”資訊。

最佳實踐

  • 標題和副標題應讓讀者知道他們將在頁面上找到什麼。
  • 它們應簡潔準確地描述內容。
  • 標題應簡短（不超過八個詞），切中要點，並使用清晰、主動的語言書寫。
  • 您應避免使用雙關語、誘導性內容和文化典故。
  • 跳過冠詞（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 個空格。
  • 省略程式碼時使用省略號 ( ... )。

標註

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

最佳實踐

  • 將“警告”、“重要”或“注意”一詞加粗。不要將標註內的內容加粗。
  • 最好避免在頁面上放置過多的文字標註。如果使用過多，它們會顯得雜亂無章，並且會降低其影響力。
文字標註使用場景顏色或標註框
警告使用“警告”標籤向讀者提示可能導致硬體損壞或資料丟失的操作。紅色
✅ 示例：警告：當您使用 docker login 命令時，您的憑據儲存在主目錄中的 .docker/config.json 檔案中。密碼在該檔案中經過 base64 編碼。
重要使用“重要”標籤向讀者提示可能導致較小問題操作。黃色
✅ 示例：更新 Docker Desktop 條款
注意對於可能不適用於所有讀者，或者資訊與主題無關的資訊，請使用“注意”標籤。藍色
✅ 示例：刪除倉庫將刪除其中包含的所有映象及其構建設定。此操作無法撤消。

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

在文件中說明如何瀏覽 Docker Desktop 或 Docker Hub 使用者介面時

  • 始終使用位置，然後是動作。例如：從可見性下拉列表（位置）中，選擇“公共”（動作）。
  • 簡明扼要。例如：正確：選擇儲存。 錯誤：選擇儲存以使更改生效。
  • 如果某個步驟必須包含原因，請以原因開頭。這有助於使用者更快地瀏覽。正確：要檢視更改，請在合併請求中選擇連結。 錯誤：在合併請求中選擇連結以檢視更改。

可選步驟

如果某個步驟是可選的，請以單詞“可選”開頭，後跟句點。

例如：

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 |