语法和风格

目录

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

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

首字母缩略词是你可以作为一个词来发音的缩写，例如 ROM（read only memory 的缩写）。其他例子包括 radar 和 scuba，它们最初是首字母缩略词，但现在本身已被视为词汇。

词首字母缩写是一种首字母缩略词，由一组首字母组成，用作名称或表达式的缩写。如果你在口语对话中使用该缩写词，你将清晰地发音每个字母：H-T-M-L 表示 Hypertext Markup Language。

最佳实践

  • 首次使用时，请拼写出不那么常见的首字母缩略词或词首字母缩写，然后在括号中加上该缩写。之后，在页面的其余部分或文档中，单独使用该缩写。

“你可以使用单点登录 (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 缩写，因为这可能使其看起来像名词是所有格。Your container is ready. Your container’s ready.

悬垂修饰语

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

  • ❌ 启用自动注销后，你的用户会注销。
  • ✅ 当你启用自动注销时，你的用户会注销。

日期

日期应使用美式格式：月日，年，例如 2021 年 6 月 26 日。

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

小数和分数

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

标点符号

冒号和分号

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

逗号

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

破折号和连字符

  • 当你想让读者停顿、创建插入语或强调特定词语或短语时，请谨慎使用长破折号 (—)。长破折号的两侧始终留有空格。
  • 使用短破折号 (–) 表示数字、日期或时间范围。
  • 使用连字符将两个或多个词连接起来，形成修饰名词的复合形容词。连接词语形成复合形容词的目的是区分其与单独使用的形容词的含义（例如，“最新文档”、“一次性付款”和“库存充足的橱柜”）。你还可以使用连字符来
    • 避免元音的尴尬重叠。例如“semi-independence*”或“re-elect”。
    • 防止某些词语的误读。例如，“Re-collect”意为再次收集；如果没有连字符，单词“recollect”具有不同的含义。

感叹号

避免使用感叹号。

括号

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

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.