语法和风格

目录

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

首字母缩略词和缩写

首字母缩略词是指可以作为单词发音的缩写，例如 ROM（只读内存）。其他例子包括 radar 和 scuba，它们最初是首字母缩略词，但现在被认为是独立的单词。

缩写是一种首字母缩略词，它由作为名称或表达式的缩写的首字母组合而成。如果您在口语对话中使用该缩写，您将逐个字母发音：H-T-M-L 代表超文本标记语言。

最佳实践

  • 第一次使用时，拼写出鲜为人知的首字母缩略词或缩写，然后在括号中使用首字母缩略词或缩写。在此之后，在页面或文档的其余部分，仅使用首字母缩略词或缩写。

“您可以使用单点登录 (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 缩写，因为这会使其看起来像名词是所有格。您的容器已准备好。您的容器已准备好。

悬垂修饰语

避免 悬垂修饰语，其中从句动词的主语不明确

  • ❌启用自动注销后，您的用户将注销。
  • ✅启用自动注销后，您的用户将注销。

日期

日期应使用美国的月日年格式：2021 年 6 月 26 日。

尽可能使用月份的全称（2022 年 10 月 1 日）。如果空间受限，则使用 3 个字母的缩写后跟句点（2022 年 10 月 1 日）。

小数和分数

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

最佳实践

  • 始终将小数至少保留到百分位（33.76）。
  • 在表格中，将小数点对齐。
  • 对于小于 1 的十进制分数，在小数点前添加一个零 (0.5 厘米)。

列表

列表是分解复杂想法并使其更易于阅读和扫描的好方法。

最佳实践

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

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

  • 某些内容类型可以使用包含 10 个项目的项目符号列表，但最好将较长的列表分解成几个列表，每个列表都有自己的小标题或引言。

  • 永远不要创建只有一个项目符号的项目符号列表，也永远不要使用破折号来指示项目符号列表。

  • 如果您的列表项是片段，请大写列表项以方便扫描，但不要使用结尾标点符号。示例

    我去商店买了

    • 牛奶
    • 面粉
    • 鸡蛋

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

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

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

    1. 顶级
    2. 顶级
      1. 子步骤
      2. 子步骤

数字

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

  • 将 1 到 9 的数字拼写出来，除非是度量单位，例如 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

标点符号

冒号和分号

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

逗号

  • 使用序列逗号或牛津逗号——在三个或三个以上项目的列表中，在并列连词（和、或）之前使用逗号。
  • 如果一个序列包含三个以上项目，或者项目很长，请考虑使用项目符号列表来提高可读性。

破折号和连字符

  • 谨慎使用 em 破折号 (-)，当您希望读者停顿、创建插入语或强调特定单词或短语时使用。 em 破折号两侧始终留有空格。
  • 使用 en 破折号 (-) 表示数字、日期或时间的范围。
  • 使用连字符连接两个或多个单词以构成位于名词之前的复合形容词。连接单词以构成复合形容词的目的是为了区分与单独使用的形容词不同的含义（例如，“最新文档”、“一次性付款”和“库存充足的橱柜”。您还可以使用连字符来
    • 避免元音的尴尬重复。例如，“半独立”或“重新选举”。
    • 防止某些单词的误读。例如，“重新收集”表示再次收集；不使用连字符，“回忆”这个词则具有不同的含义。

感叹号

避免使用感叹号。

括号

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