語法和風格

目錄

Docker 文件應始終使用美式英語和美式語法編寫。

首字母縮略詞和詞首字母縮寫

首字母縮略詞是你可以作為一個詞來發音的縮寫，例如 ROM（read only memory 的縮寫）。其他例子包括 radar 和 scuba，它們最初是首字母縮略詞，但現在本身已被視為詞彙。

詞首字母縮寫是一種首字母縮略詞，由一組首字母組成，用作名稱或表示式的縮寫。如果你在口語對話中使用該縮寫詞，你將清晰地發音每個字母：H-T-M-L 表示 Hypertext Markup Language。

最佳實踐

  • 首次使用時，請拼寫出不那麼常見的首字母縮略詞或詞首字母縮寫，然後在括號中加上該縮寫。之後，在頁面的其餘部分或文件中，單獨使用該縮寫。

“你可以使用單點登入 (SSO) 登入 Notion。你可能需要請求管理員啟用 SSO。”

  • 如果首字母縮略詞或詞首字母縮寫比完整短語更常用，例如 URL、HTML，則無需遵循此拼寫規則。
  • 檔案型別（JPEG 檔案）的首字母縮略詞使用全大寫。
  • 複數首字母縮略詞不使用撇號。✅URLs ❌URL’S
  • 避免在標題中首次使用首字母縮略詞。如果首字母縮略詞首次出現在標題中，請在隨後的第一個正文中介紹該縮寫詞（在括號中，緊隨拼寫出的術語之後）。

粗體和斜體

除非你指的是 UI 文字或使用者定義的文字，否則不應對文字新增強調。清晰、重點突出的措辭使句子的主語明確。

最佳實踐

  • 不要使用粗體來指代功能名稱。
  • 謹慎使用斜體，因為這種格式在數字體驗中可能難以閱讀。值得注意的例外是文章、部落格文章或規範文件的標題。

大小寫

幾乎所有內容都使用句首大寫。句首大寫意味著只將第一個單詞大寫，就像在標準句子中一樣。

以下內容元素應使用句首大寫：

  • 網路研討會和活動的標題
  • 所有內容型別中的標題和副標題
  • 行動號召
  • 方框文字中的標題
  • 表格中的列和行標題
  • 連結
  • 句子（當然）
  • UI 中的任何內容，包括導航標籤、按鈕、標題

最佳實踐

  • 一般來說，最好避免在大多數內容型別中使用全部大寫。它們更難掃描且佔用更多空間。雖然全部大寫可以傳達強調，但它們也可能給人一種喊叫的印象。
  • 如果公司名稱全部為小寫或全部為大寫字母，請遵循其風格，即使在句子的開頭也是如此：DISH 和 bluecrux。如有疑問，請檢視公司網站。
  • Docker 解決方案使用標題大小寫：Docker Extensions、Docker Hub。
  • 如果職務名稱緊接在姓名之前，則將其大寫（執行長 Scott Johnston）。
  • 不將姓名後或一般引用的職務名稱大寫（Scott Johnston，Docker 執行長）。
  • 引用部門名稱時將其大寫，但如果指的是工作領域而非實際部門，則使用小寫。
  • 在引用特定使用者介面文字（例如按鈕標籤或選單項）時，請使用使用者介面中顯示的大小寫。

縮寫

縮寫是由於原始單詞或短語中省略了字母而產生的，例如 you're 代表 you are 或 it's 代表 it is。

遵循我們的會話式方法，幾乎所有內容型別都允許使用縮寫。但不要過度。一個句子中過多的縮寫會使閱讀困難。

最佳實踐

  • 保持一致性 - 不要在正文或 UI 文字中在縮寫及其完整形式之間切換。
  • 儘可能避免使用否定縮寫（can't、don't、wouldn't 和 shouldn't）。嘗試重寫你的句子，以符合我們關注解決方案而非問題的有用方法。
  • 切勿將名詞與 is、does、has 或 was 縮寫，因為這可能使其看起來像名詞是所有格。Your container is ready. Your container’s ready.

懸垂修飾語

避免懸垂修飾語，即從句動詞的主語不明確

  • ❌ 啟用自動登出後，你的使用者會登出。
  • ✅ 當你啟用自動登出時，你的使用者會登出。

日期

日期應使用美式格式：月日，年，例如 2021 年 6 月 26 日。

如果可能，請使用月份的全名（2022 年 10 月 1 日）。如果空間有限，請使用 3 個字母的縮寫，後跟一個句號（Oct. 1. 2022）。

小數和分數

在所有 UI 內容和技術文件中，使用小數而不是分數。

最佳實踐

  • 小數位始終至少保留到百分位（33.76）。
  • 在表格中，小數點對齊。
  • 對於小於 1 的小數，在小數點前加零（0.5 釐米）。

列表

列表是分解複雜概念並使其更易於閱讀和掃描的好方法。

最佳實踐

  • 專案符號列表應包含相對較少的單詞或短語。對於大多數內容型別，列表中的專案數限制為五個。

  • 不要在列表項末尾新增逗號 (,) 或分號 (;)。

  • 某些內容型別可能會使用包含 10 個專案符號列表，但最好將較長的列表分解為幾個列表，每個列表都有自己的副標題或介紹。

  • 切勿建立只有一個專案符號的專案符號列表，也切勿使用破折號表示專案符號列表。

  • 如果你的列表項是片段，為了便於掃描，請將列表項大寫，但不要使用結尾標點符號。示例

    我去商店買

    • 牛奶
    • 麵粉
    • 雞蛋

  • 確保所有列表項都平行。這意味著你應該以相同的方式組織每個列表項。它們都應該是片段，或者都應該是完整的句子。如果你用動詞開頭一個列表項，那麼所有列表項都應該用動詞開頭。

  • 列表中的每個專案都應以大寫字母開頭，除非它們是引數或命令。

  • 巢狀的順序列表用小寫字母標記。例如

    1. 頂級
    2. 頂級
      1. 子步驟
      2. 子步驟

數字

在內容中處理數字時，最佳實踐包括

  • 拼寫出從一到九的數字，但度量單位除外，例如 4 MB。
  • 兩位或更多位的數字用阿拉伯數字表示（10、625、773,925）。
  • 重構句子，而不是以數字開頭（除非是年份）。
  • 在示例中引用數字時，請按照任何附帶的螢幕截圖中的顯示方式寫出。
  • 在示例中引用平臺上的數字時，請按照平臺上的顯示方式寫出。
  • 要抽象地引用大數字（例如數千、數百萬和數十億），請使用單詞和數字的組合。不要縮寫數字符號。
  • 避免在數字中使用逗號，因為它們在不同的文化中可能表示小數。對於五位或更多位的數字，請使用空格分隔。
    正確不正確
    10001,000
    14 58614,586
    1 390 6801,390,680

版本

編寫釋出說明的版本號時，請使用以下示例

  • 版本 4.8.2
  • v1.0
  • Docker Hub API v2

標點符號

冒號和分號

  • 冒號用於：在句子中內聯引入列表；引入專案符號或編號列表；以及提供解釋。
  • 不要使用分號。改用兩個句子。

逗號

  • 使用連串逗號或牛津逗號——在三個或更多專案的列表中，連詞（and、or）之前加一個逗號。
  • 如果系列包含三個以上專案或專案較長，請考慮使用專案符號列表以提高可讀性。

破折號和連字元

  • 當你想讓讀者停頓、建立插入語或強調特定詞語或短語時，請謹慎使用長破折號 (—)。長破折號的兩側始終留有空格。
  • 使用短破折號 (–) 表示數字、日期或時間範圍。
  • 使用連字元將兩個或多個詞連線起來，形成修飾名詞的複合形容詞。連線詞語形成複合形容詞的目的是區分其與單獨使用的形容詞的含義（例如，“最新文件”、“一次性付款”和“庫存充足的櫥櫃”）。你還可以使用連字元來
    • 避免母音的尷尬重疊。例如“semi-independence*”或“re-elect”。
    • 防止某些詞語的誤讀。例如，“Re-collect”意為再次收集；如果沒有連字元，單詞“recollect”具有不同的含義。

感嘆號

避免使用感嘆號。

括號

技術文件中不要使用括號。它們會降低句子的可讀性。