语法和文体

Table of contents

Docker 文档应始终使用美式英语和美式语法编写。

首字母缩略词和缩写词

首字母缩略词（Acronym）是一种可以作为一个单词读出来的缩写，例如，ROM（只读存储器）。其他例子包括 radar 和 scuba，它们最初是首字母缩略词，但现在被认为是独立的单词。

缩写词（Initialism）是首字母缩略词的一种，由一组首字母组成，用作名称或表达的缩写。如果你在口语对话中使用这个缩写，你会清晰地读出每个字母：H-T-M-L 代表 Hypertext Markup Language。

最佳实践

  • 在首次使用时，完整拼写出不太为人熟知的首字母缩略词或缩写词，然后在括号中跟上该缩写。此后，在页面或文档的其余部分，单独使用该缩写。

‘你可以使用单点登录 (SSO) 登录 Notion。你可能需要请求管理员启用 SSO。’

  • 如果首字母缩略词或缩写词比完整短语更常用，例如 URL、HTML，则无需遵循此拼写规则。
  • 文件类型的首字母缩略词使用全大写（a JPEG file）。
  • 复数形式的首字母缩略词不要使用撇号。 ✅URLs ❌URL’S
  • 避免在标题中首次使用首字母缩略词。如果首字母缩略词首次出现在标题中，请在紧随其后的正文文本中引入该缩写（在括号内，跟在完整拼写的术语之后）。

粗体和斜体

除非你指的是 UI 文本或用户定义的文本，否则不应为文本添加强调。清晰、前置的措辞能让句子的主题一目了然。

最佳实践

  • 不要使用粗体来指代功能名称。
  • 谨慎使用斜体，因为这种格式在数字体验中可能难以阅读。 明显的例外是文章、博客文章或规范文档的标题。

大小写

几乎所有内容都应使用句首大写（sentence case）。句首大写意味着只将第一个单词的首字母大写，就像在标准句子中一样。

以下内容元素应使用句首大写：

  • 网络研讨会和活动的标题
  • 所有内容类型中的标题和副标题
  • 行动号召 (Calls to action)
  • 框内文本的标题
  • 表格中的列标题和行标题
  • 链接
  • 句子（当然）
  • UI 中的任何内容，包括导航标签、按钮、标题

最佳实践

  • 作为一般规则，最好避免在大多数内容类型中使用全大写。它们更难浏览，并且占用更多空间。虽然全大写可以传达强调，但也可能给人以大喊大叫的印象。
  • 如果公司名称全为小写或全为大写字母，请遵循其风格，即使在句子开头也是如此：DISH 和 bluecrux。如有疑问，请查看该公司的网站。
  • Docker 解决方案使用标题大写（Title Case）：Docker Extensions, Docker Hub。
  • 如果职位名称紧接在姓名之前，则将其首字母大写（Chief Executive Officer Scott Johnston）。
  • 如果职位名称跟在姓名之后或是泛指，则不要将其首字母大写（Scott Johnston, chief executive officer of 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.

悬垂修饰语

避免使用悬垂修饰语，即从句中动词的主语不明确：

  • ❌ After enabling auto-log-out, your users are logged out. (启用自动注销后，你的用户会被注销。)
  • ✅ When you enable auto-log-out, your users are logged out. (当你启用自动注销时，你的用户会被注销。)

日期

日期应使用月、日、年的美式格式：June 26, 2021。

尽可能使用月份的全名（October 1, 2022）。如果空间有限，请使用 3 个字母的缩写，后跟句点（Oct. 1. 2022）。

小数和分数

在所有 UI 内容和技术文档中，使用小数而不是分数。

最佳实践

  • 始终将小数至少保留到百分位（33.76）。
  • 在表格中，按小数点对齐小数。
  • 对于小于 1 的小数分数，在小数点前添加零（0.5 cm）。

列表

列表是分解复杂想法、使其更易于阅读和浏览的好方法。

最佳实践

  • 项目符号列表应包含相对较少的单词或短语。对于大多数内容类型，将列表中的项目数量限制为五个。

  • 不要在列表项的末尾添加逗号 (,) 或分号 (;)。

  • 某些内容类型可能使用包含 10 个项目的项目符号列表，但最好将较长的列表拆分为几个列表，每个列表都有自己的副标题或介绍。

  • 切勿创建只有一个项目符号的列表，也切勿使用破折号来表示项目符号列表。

  • 如果你的列表项是片段，为了便于浏览，请将列表项的首字母大写，但不要使用句末标点。 示例：

    I went to the shops to buy: (我去商店购买：)

    • Milk (牛奶)
    • Flour (面粉)
    • Eggs (鸡蛋)

  • 确保所有列表项都是平行的。这意味着你应该以相同的方式构建每个列表项。它们都应该是片段，或者都应该是完整的句子。如果你以动词开头一个列表项，那么所有列表项都应以动词开头。

  • 列表中的每个项目都应以大写字母开头，除非它们是参数或命令。

  • 嵌套的顺序列表用小写字母标记。例如：

    1. Top level (顶层)
    2. Top level (顶层)
      1. Child step (子步骤)
      2. Child step (子步骤)

数字

在内容中处理数字时，最佳实践包括：

  • 拼写从一到九的数字，但度量单位（如 4 MB）除外。
  • 用数字表示两位或更多位数的数字（10, 625, 773,925）。
  • 重构句子，而不是以数字开头（除非是年份）。
  • 在示例中引用数字时，按照任何附带屏幕截图中显示的方式书写。
  • 在示例中引用数字时，按照平台上的显示方式书写。
  • 要抽象地指代大数字（如千、百万、十亿），请使用单词和数字的组合。不要缩写数字标识符。
  • 避免在数字中使用逗号，因为它们在不同文化中可能表示小数。对于五位或更多位的数字，使用空格进行分隔。
    正确 错误
    1000 1,000
    14 586 14,586
    1 390 680 1,390,680

版本号

为发布说明编写版本号时，请使用以下示例：

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

标点符号

冒号和分号

  • 使用冒号来：在句子中引入行内列表；引入项目符号或编号列表；以及提供解释。
  • 不要使用分号。改用两个句子。

逗号

  • 使用序列逗号或牛津逗号 - 在三个或更多项目的列表中，在并列连词（and, or）之前加一个逗号。
  • 如果一个系列包含超过三个项目或项目较长，考虑使用项目符号列表来提高可读性。

破折号和连字符

  • 谨慎使用长破折号 (—)，当你想让读者停顿、创建插入语或强调特定单词或短语时。始终在长破折号两侧留一个空格。
  • 使用短破折号 (–) 表示数字、日期或时间的范围。
  • 使用连字符将两个或多个单词连接起来，形成位于名词之前的复合形容词。将单词连接形成复合形容词的目的是将其含义与单独使用的形容词区分开来（例如，‘up-to-date documentation’（最新的文档），‘lump-sum payment’（一次性付款），和 ‘well-stocked cupboard’（存货充足的橱柜）。你也可以使用连字符来：
    • 避免元音尴尬地重复。例如 ‘semi-independence’（半独立），或 ‘re-elect’（再次选举）。
    • 防止某些单词被误读。例如 ‘Re-collect’ 意味着再次收集；没有连字符的单词 recollect 有不同的含义（回想）。

感叹号

避免使用感叹号。

括号

不要在技术文档中使用括号。它们会降低句子的可读性。