文法與風格

目錄

Docker 文件應始終以美式英文撰寫，並使用美式文法。

縮寫和首字母縮寫詞

縮寫是指您可以像單詞一樣發音的縮寫，例如 ROM（代表唯讀記憶體）。其他例子包括雷達和水肺，它們最初是縮寫，但現在被視為獨立的單詞。

首字母縮寫詞是一種縮寫，由一組用作名稱或表達式縮寫的首字母組成。如果您在口語對話中使用縮寫，您會念出每個字母：H-T-M-L 代表超文字標記語言。

最佳實務

  • 首次使用鮮為人知的縮寫或首字母縮寫詞時，請拼寫出來，然後在括號中加上縮寫或首字母縮寫詞。之後，在頁面或文件的其餘部分中，單獨使用縮寫或首字母縮寫詞。

「您可以使用單一登入 (SSO) 登入 Notion。您可能需要請您的管理員啟用 SSO。」

  • 如果縮寫或首字母縮寫詞比完整片語更常用，例如 URL、HTML，則您不需要遵循此拼寫規則。
  • 檔案類型縮寫使用全大寫（JPEG 檔案）。
  • 不要使用撇號表示縮寫的複數形式。 ✅URLs ❌URL’S
  • 避免在標題或副標題中首次使用縮寫。如果縮寫的首次使用是在標題或副標題中，請在後面的第一個正文中介紹縮寫（在括號中，拼寫出完整術語之後）。

粗體和斜體

除非您指的是 UI 文字或使用者定義的文字，否則您不應為文字添加強調。清晰、重點突出的措辭可以清楚地表達句子的主旨。

最佳實務

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

大小寫

幾乎所有內容都使用句子式大小寫。句子式大小寫表示只大寫第一個單詞，就像在標準句子中一樣。

以下內容元素應使用句子式大小寫

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

最佳實務

  • 一般來說，最好避免在大多数内容类型中使用全大寫。它們更難以掃描，並且佔用更多空間。雖然全大寫可以表達強調，但它們也可能給人一種大喊大叫的感覺。
  • 如果公司名稱全部小寫或全部大寫，請遵循他們的風格，即使在句首也是如此：DISH 和 bluecrux。如有疑問，請查看該公司的網站。
  • Docker 解決方案使用標題式大小寫：Docker Extensions、Docker Hub。
  • 如果職稱緊接在姓名之前，則將其大寫（執行長 Scott Johnston）。
  • 不要大寫姓名後面的職稱或一般參考（Docker 執行長 Scott Johnston）。
  • 當您指的是部門的名稱時，請將部門名稱大寫，但如果您談論的是工作領域而不是實際的部門，請使用小寫。
  • 當引用特定的使用者介面文字（例如按鈕標籤或選單項目）時，請使用使用者介面中顯示的相同大小寫。

縮寫

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

遵循我們的會話方式，在幾乎所有內容類型中都可以使用縮寫。只是不要過度使用。句子中過多的縮寫會使閱讀變得困難。

最佳實務

  • 保持一致 - 不要在正文或 UI 文字中在縮寫及其拼寫出的等效詞之間切換。
  • 盡可能避免使用否定縮寫（can't、don't、wouldn't 和 shouldn't）。嘗試改寫您的句子，使其與我們注重解決方案而非問題的 helpful 方法相一致。
  • 永遠不要將名詞與 is、does、has 或 was 縮寫，因為這會使名詞看起來像是所有格。 Your container is ready. Your container’s ready.

懸垂修飾語

避免懸垂修飾語，其中子句動詞的主詞不清楚

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

日期

您應該使用美式日期格式：月、日、年： 2021 年 6 月 26 日。

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

小數和分數

在所有 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

標點符號

冒號和分號

  • 使用冒號：在句子中引入行內清單；引入項目符號或編號清單；以及提供說明。
  • 不要使用分號。請改用兩個句子。

逗號

  • 使用序列逗號或牛津逗號 - 在三個或更多項目的清單中，協調連詞（和、或）之前的逗號。
  • 如果序列包含三個以上的項目或項目很長，請考慮使用項目符號清單以提高可讀性。

破折號和連字號

  • 當您希望讀者停頓、創建插入語或強調特定單詞或片語時，請謹慎使用長破折號 (-)。始終在長破折號的兩側留一個空格。
  • 使用短破折號 (-) 來表示數字、日期或時間的範圍。
  • 使用連字符號 (-) 將兩個或多個詞連接起來，形成修飾名詞的複合形容詞。連接詞語形成複合形容詞的目的是為了區別單獨使用這些形容詞時的含義（例如「最新的文件」、「一次性付款」和「儲備充足的櫥櫃」）。您也可以使用連字符號來
    • 避免元音字母的尷尬重複。例如「半獨立*」*或「重新選舉」。
    • 防止某些詞語被誤讀。例如，「Re-collect」的意思是再次收集；如果不使用連字符號，單詞「recollect」則有不同的含義（回憶）。

驚嘆號

避免使用驚嘆號。

括號

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