语法和风格

目录

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 有不同的含义。

感叹号

避免使用感叹号。

括号

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

页面选项