語法和風格

目錄

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

首字母縮略詞和首字母詞

首字母縮略詞是一種可以作為單詞發音的縮寫，例如 ROM（只讀儲存器）。其他例子包括 radar 和 scuba，它們最初是首字母縮略詞，但現在被認為是獨立的單詞。

首字母詞是一種首字母縮略詞，由一組首字母組成，用作名稱或表達的縮寫。如果您在口語對話中使用該縮寫，您會逐個發音：Hypertext Markup Language 的 H-T-M-L。

最佳實踐

  • 對於不太知名的首字母縮略詞或首字母詞，首次使用時請寫全稱，然後在括號中附上縮寫。此後，在頁面或文件的其餘部分，僅使用該縮寫。

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

  • 如果首字母縮略詞或首字母詞比其完整短語更常用，例如 URL、HTML，則無需遵循寫全稱的規則。
  • 檔案型別的首字母縮略詞（例如 JPEG 檔案）請使用大寫。
  • 多個首字母縮略詞不用撇號。✅URLs ❌URL’S
  • 避免在標題或副標題中首次使用首字母縮略詞。如果首次使用首字母縮略詞是在標題或副標題中，請在其後的第一段正文中介紹該縮寫（在寫全稱後，用括號附上縮寫）。

粗體和斜體

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

最佳實踐

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

大寫

幾乎所有內容都使用句首大寫（Sentence case）。句首大寫是指僅將第一個單詞大寫，就像標準句子一樣。

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

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

最佳實踐

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

縮寫詞

縮寫詞是將原始單詞或短語中的字母省略而形成的，例如 you're 代表 you are，it's 代表 it is。

遵循我們對話式的寫作風格，幾乎所有內容型別都可以使用縮寫詞。但不要濫用。一個句子中使用過多縮寫詞會影響閱讀。

最佳實踐

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

懸垂修飾語

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

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

日期

日期應使用美式 月 日, 年 格式：June 26, 2021。

可能的情況下，使用月份全稱（October 1, 2022）。如果空間有限，使用 3 個字母的縮寫後跟句號（Oct. 1. 2022）。

小數和分數

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

最佳實踐

  • 小數至少保留到小數點後兩位（33.76）。
  • 在表格中，小數應按小數點對齊。
  • 小於 1 的小數分數，在小數點前加零（0.5 cm）。

列表

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

最佳實踐

  • 無序列表應包含相對較少的單詞或短語。對於大多數內容型別，列表項的數量限制在五個以內。

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

  • 某些內容型別可能使用包含 10 個專案的無序列表，但最好將較長的列表分成幾個列表，每個列表都有自己的副標題或引言。

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

  • 如果您的列表項是片段，為了易於掃描請將列表項首字母大寫，但不要使用末尾標點符號。示例

    我去商店買了

    • 牛奶
    • 麵粉
    • 雞蛋

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

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

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

    1. 頂層
    2. 頂層
      1. 子步驟
      2. 子步驟

數字

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

  • 拼寫出一到九的數字，測量單位除外，例如 4 MB。
  • 兩位或更多位的數字使用阿拉伯數字表示 (10, 625, 773,925)。
  • 重構句子，而非以數字開頭（年份除外）。
  • 在示例中引用數字時，請按照隨附截圖中的顯示方式書寫。
  • 在示例中引用平臺上的數字時，請按照平臺上的顯示方式書寫。
  • 抽象地指代大數字（如 thousand, million, billion）時，使用單詞和數字的組合。不要縮寫數字表示符。
  • 避免在數字中使用逗號，因為在不同文化中逗號可能表示小數點。對於五位或更多位的數字，使用空格分隔。
    正確不正確
    10001,000
    14 58614,586
    1 390 6801,390,680

版本

為發行說明編寫版本號時，使用以下示例：

  • version 4.8.2
  • v1.0
  • Docker Hub API v2

標點符號

冒號和分號

  • 使用冒號來：在句中引入內嵌列表；引入無序或有序列表；提供解釋。
  • 不要使用分號。請改用兩個句子。

逗號

  • 使用序列逗號或牛津逗號——在三個或更多專案的列表中，位於並列連詞（and, or）之前的逗號。
  • 如果系列包含三個以上專案或專案較長，考慮使用無序列表以提高可讀性。

破折號和連字元

  • 謹慎使用長破折號 (-) 來提示讀者停頓、建立插入語或強調特定單詞或短語。長破折號兩側始終留有空格。
  • 使用短破折號 (-) 表示數字、日期或時間範圍。
  • 使用連字元將兩個或更多單詞連線起來，構成修飾名詞的複合形容詞。... 您還可以使用連字元來：
    • 避免母音重複造成的拗口。例如 ‘semi-independence*’,* 或 ‘re-elect’。
    • 防止誤讀某些單詞。例如 ‘Re-collect’ 指再次收集；沒有連字元，單詞 recollect 有不同的含義。

感嘆號

避免使用感嘆號。

括號

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

頁面選項