Docker文档风格指南

Docker文档的风格及语法约定

风格标准

随着时间的推移，不同的出版社区会使用他们喜欢的编码和语法标准来发表他们的文章，这些标准即所谓的“风格“。一般情况下，docker的文档使用的描述性标准来自于美联社（AP）的风格，如果你对一些句法，语法及词汇有问题，你可以先参照AP指南，如果你没有AP指南的相关文档，你可以在网上找到具体的解释，如果你对网上的解释不满意，你可以询问我们的维护人员。

尽管如此，你也不要太在意使用正确的样式，我们宁愿你提交的是有用的信息而不是那些遵循了标准却没有用的信息，Docker的科技作家总是很乐意的帮助你的文章，我们绝不会批判你的文章。

该文档是以80列宽的标准来写的，是为了在终端下使用更方便，你可以自己设置你喜欢的编辑器以适应这个文档

散文的风格（Prose style）

在一般情况下，尽量写说明性的文章，我们喜欢简短，单一句子或3-5句话的段落，而且尽量选择一些简单而精确地词汇，避免创建一些新的术语、模糊的措辞或是使用许多行业的术语。比如：尽可能使用”use“而不是用”leverage “。

在编写文档时，你不必刻意的将它写的很规范，假设你是在写一篇大学基础的演讲稿，因为如果你的文章简单清晰明了，它会很容易的翻译出来。

最好的方法就是假设Docker的用户都是一般大学的学历，阅读能力都至少在“16”级的水平（就是有一个大学学位），你可以使用一个可读性的测试器来帮助知道你的判断。比如：”Containers should be ephemeral”，如果测试器的分数在13即左右，就意味着是大一的水平，它是可以接受的。

在所有的情况下，相比于正式的语言，我们更喜欢用简介清晰的非正式语言进行交流，请不要认为编写文档就是在写可以文章。

隐喻和比喻性语言（Metaphor and figurative language）

为了不让文章显得是直接以英语为第二语言（ESL），应尽量避免使用隐喻或其它比喻性的语言来描述事物。因为这涉及到许多文化和社会因素，让一些读者难以理解你的比喻。

特定的约定（Specific conventions）

以下是来自美联社（AP）关于编写风格的具体的建议（和一些偏差）：

缩写（Contractions）

只要你的文章不会变的太随意，我们都能够接受你在文章中使用缩写形式，但在使用缩写形式时，确保用上引号。

在句子中使用破折号（Use of dashes in a sentence）

破折号有短破折号（-）和长破折号（—），破折号可以用来分隔句子。例如： This is an example of a Docker client – which uses the Big Widget to run – and does x, y, and z.

在使用破折号时要谨慎，当有逗号和括号在一起时还要考虑它们在一起是否合适，我们始终提倡使用简短的句子。

更多有用的信息：Grammar Girl site

代词（Pronouns）

在文档中使用第一人称或第二人称都是可以的。特别是，在指代Docker时使用“we”,如果是用户就是用“you”,比如：”We built the exec command so you can resize a TTY session.”

尽可能避免使用性别代词（”he” 或 “she”, 等.），如果在改写句子时，代词并不是必要的，如果要使用的话，可以使用“they”代替。如果你不可避免的要使用到性别代词，你可以用一个并一直用下去，一个常识是使用作者的性别的代词，但你想使用其他的也没关系。

大写（Capitalization）

在一般情况下

只有文章中的专有名词才可以使用大写，通常，都要遵守这条规则，避免使用大写来表示强调或“特殊性”。

当谈及其他公司或技术时，“Docker”都要大写，唯一除外就是当“docker”出现在代码中时要小写。

起始句子

尽量避免用代码开头。

标题

在标题中通常只有第一个字母要大写（句子中的单词通常也要大写，如：“Docker”），不要让标题中的每个单词的首字母大写，通常，我们坚持使用美联社的标题风格

句号（Periods）

一句话结束后要加一个空格

查看下面的 “Lists”了解如何使用列表项

缩略语（Abbreviations and acronyms）

Exempli gratia（e.g.)， id est（i.e.），这些始终都是成对的，并且后面会有一个逗号。

首字母缩略词通常在后面加一个“s”代表复数，如：PCs, OSs.

在页面中首次使用一个术语时，应将它的完整形式写出来，之后你就可以使用它的缩写形式，如：Red Hat Enterprise Linux (RHEL)，唯一常见的例外就是：非技术性的缩略词如AKA和ASAP。记住除i.e. 和 e.g.之外的缩略词首字母要大写。

和e.g. i.e.不同的是，缩略词后面没有必要加句号，如 PC 而不是 P.C.

列表（Lists）

当使用列表时，请注意如下规则:

当被列出的项是相互独立且顺序不重要时，请使用项目符号

对于必须按顺序的步骤或在前文中提到的请使用编号列表，比如：如果文章中这样写道：”There are three config settings available for SSL, as follows:“，你就要在随后的列表中对每一个配置进行编号。

在所有的列表中，如果有一项是一个完整的句子，那它就应该以句号结尾。列表的每一项首字母要大写。

数字（Numbers）

在正文和标题中使用数字时请从’one’到’ten’，11以上请用数字。

备注（Notes）

  1. 请谨慎使用note，在文章某些需要引起读者注意的地方，可以使用note，在使用note时请使用如下的格式：

**Note:**

One line of note text

  1. another line of note text

避免过度使用”i.e.“

在使用”i.e.“时，它会给读者增加在理解上的负担，避免使用：”This is a thing, i.e., it is like this“，你可以这样说：”This thing is …“。

首选用法（Preferred usages）

Login 和 log in. 的比较

“login”是一个名词（一个单词），比如在 “Enter your login”当中，”Log in”是一个复合动词（两个单词），比如：”Log in to the terminal”.

牛津逗号（Oxford comma）

和美联社风格（AP）不同的是，在Docker文档中，都使用了牛津逗号（Oxford comma），尽管在这个方面有很多的争议，但是我们不会改变我们的心态，就是这样！

编码和UI风格（Code and UI text styling）

对于命令行或其他来自于CLI的输入或输出，我们需要一个统一的编码字体，如monospace, sans-serif，这也包括文件的路径（如：/etc/hosts/docker.conf），如果文本是被包括在反括号中，markdown会将文本的格式变成代码的格式。

命令行的文本应逐字被引用，尽管它包含错误或它的风格违背了指南的风格，你可以在最后加上”(sic)” ，表明是引用中的错误而不是指南中的错误。

GUI中的文本（如：菜单的文本，按钮中的文本），应该写在双层引用中，文本中应该使用相同的大小写格式，比如在GUI中，点击“Continue”保存设置。

文本中使用的键盘指令和热键应该大写，如Ctrl-D

当编写命令行的例子时，可以通过写一些与他们在shell上看到的类似的例子来给使用者提示：

  • 首行缩进4个空格，可以展示出类似代码块的风格
  • 命令行请用 $ 符号开头，便于区分
  • 程序的输出不需要加前缀
  • 评论请以 # 作为前缀
  • 容器中的shell命令，请用 $$ 开头

所有的示例代码都需要测试，确保都是正确的，这样用户就能直接粘贴复制到命令行执行了。

PULL请求（Pull requests）

PULL请求的过程是非常全面的，我们要确保每一个对文档的修改都是最好的，一个好的PR（Pull Request）会做到如下几步：

  • 解释为什么添加这样的修改
  • 指明潜在的问题及疑问
  • 向公司或社区的专家学者寻求过帮助
  • 鼓励核心开发人员及其它相关人员提供反馈和建议

编写PULL请求是重点，并且还要有一个明确的目标来激励你完成以上的步骤。提交完毕后，维护人员将会验证文档，并标识出在沟通及演示文稿中存在的潜在问题

提交信息（Commit messages）

要写出清晰，有用的提交信息，可以参考这些推荐文章。

超链接（Links）

为了易用性和可用性，在使用超链接时尽量避免使用“click here”这样的句子，超链接的文字要尽可能的描述链接的内容，比如相面的“提交信息”一节。

你可以使用相对链接（../linkeditem）链接到Docker文档的其他页面。

图像（Graphics）

当你需要添加一个图像时，尽可能让文件的大小最小。你也可以免费向我们寻求帮助，来解决图像大小的问题，通常图像放在同一目录，便于.md文件引用它们，如果子目录已经存在图像，那就直接使用。

关于图像的格式，PNG最好的，当然GIF和JPG格式的也可以。如果你引用了用户界面的特定部分的图像，使用 call-outs (circles and arrows or lines)来突出显示你所引用的图像，call-outs 中线条的宽度不应超过5像素，call-outs 中尽量使用红色。

图像中一定要使用描述性的文本（alt-text），这会极大的帮助用户更理解这个问题。

最后，还要确保你有权使用任何图象。