语法和风格

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

首字母缩略词和首字母缩略词

首字母缩写词是您所说的单词的缩写，例如 ROM（只读存储器）。其他例子包括雷达和水肺，它们最初是缩写词，但现在被认为是独立的单词。

首字母缩略词是一种首字母缩略词，由一组用作名称或表达式缩写的首字母组成。如果您在口语对话中使用该缩写词，您将发音每个字母：HTML 表示超文本标记语言。

最佳实践

  • 在第一次使用时拼写出不太为人所知的缩写词或缩写词，然后在括号中添加缩写词或缩写词。此后，在页面或文档的其余部分中，单独使用首字母缩略词或首字母缩写词。

“您可以使用单点登录 (SSO) 登录到 Notion。您可能需要请求管理员启用 SSO。”

  • 如果首字母缩略词或缩写比完整短语更常用，例如 URL、HTML，则无需遵循此拼写规则。
  • 文件类型（JPEG 文件）的首字母缩略词全部大写。
  • 不要对复数缩略词使用撇号。 ✅网址 ❌网址
  • 避免在标题或标题中首次使用首字母缩略词。如果首字母缩略词首次在标题或标题中使用，请在随后的第一个正文文本中引入首字母缩略词（在括号中，在拼写出来的术语后面）。

粗体和斜体

除非您指的是 UI 文本或用户定义的文本，否则不应对文本添加强调。清晰、前置的措辞使句子的主题清晰。

最佳实践

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

大写

几乎所有事情都使用句首字母大写。句子大小写意味着仅将第一个单词大写，就像在标准句子中一样。

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

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

最佳实践

  • 作为一般规则，最好避免在大多数内容类型中使用全部大写。它们更难以扫描并且占用更多空间。虽然全部大写可以表达强调，但它们也可能给人大喊大叫的印象。
  • 如果公司名称全部为小写或全部大写字母，请遵循其风格，即使在句子开头：DISH 和 bluecrux。如有疑问，请查看该公司的网站。
  • 使用 Docker 解决方案的标题：Docker Extensions、Docker Hub。
  • 如果职位名称紧接在姓名之前，则将其大写（首席执行官 Scott Johnston）。
  • 不要将名字后面的职位或一般性的职位名称大写（Scott Johnston，Docker 首席执行官）。
  • 当您提及部门名称时，部门名称应大写；但如果您谈论的是工作领域而不是实际部门，则应使用小写字母。
  • 当引用特定的用户界面文本（例如按钮标签或菜单项）时，请使用用户界面中显示的相同大小写。

宫缩

缩写是由于原始单词或短语中的字母被省略而产生的，例如 you're for you are 或 it's for it is。

按照我们的对话方法，在几乎所有内容类型中使用缩写都是可以接受的。只是不要得意忘形。句子中过多的缩写会使阅读变得困难。

最佳实践

  • 保持一致 - 不要在正文或 UI 文本中的缩写和拼写对应内容之间切换。
  • 尽可能避免负面收缩（不能、不、不会、不应该）。尝试重写您的句子，以符合我们的有用方法，该方法将重点放在解决方案而不是问题上。
  • 切勿将名词与 is、does、has 或 was 联系起来，因为这会使该名词看起来像是所有格。你的容器已经准备好了。你的容器已经准备好了。

日期

您应该使用美国格式的月日年格式来表示日期：2021 年 6 月 26 日。

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

小数和分数

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

最佳实践

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

列表

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

最佳实践

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

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

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

  • 切勿创建仅包含一个项目符号的项目符号列表，也切勿使用破折号来指示项目符号列表。

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

    我go商店买了：

    • 牛奶
    • 面粉
    • 蛋

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

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

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

    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 中心 API v2

标点

冒号和分号

  • 使用冒号可以： 在句子中引入内联列表；引入项目符号或编号列表；并作出解释。
  • 不要使用分号。用两句话代替。

逗号

  • 使用序列号或牛津逗号 - 在三个或更多事物的列表中并列连词（and、or）之前的逗号。
  • 如果一个系列包含三个以上的项目或项目很长，请考虑使用项目符号列表以提高可读性。

破折号和连字符

  • 当您希望读者暂停、创建插入语句或强调特定单词或短语时，请谨慎使用破折号 (-)。始终在破折号的两侧各留一个空格。
  • 使用破折号 (-) 表示数字、日期或时间的范围。
  • 使用连字符连接两个或多个单词以形成名词前面的复合形容词。连接单词形成复合形容词的目的是为了区分单独使用的形容词的含义（例如，“最新文档”、“一次性付款”和“库存充足的橱柜”。您还可以使用连字符可以：
    • 避免尴尬的双元音。例如“半独立*”、*或“连任”。
    • 防止误读某些单词。例如“Re-collect”表示重新收集；如果没有连字符，recollect 这个词就有不同的含义。

感叹号

避免使用感叹号。

括号

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

第三方文档

如果您正在记录需要使用第三方产品的任务，请链接到第三方文档。请勿复制内容，因为这可能侵犯版权。当第三方更改或更新其产品时，它还可能导致不必要的维护负担，必须使文档保持最新。最佳做法是链接到单一事实来源。