语法和标点符号

常见样式和用法，以及常见错误

Ansible

写“Ansible”。不要写“Ansible, Inc.”或“AnsibleWorks”。此规则的唯一例外是我们在撰写法律或财务报表时。
在正文中绝不单独使用徽标。始终使用与句子中其他部分相同的字体。
在美国，公司是单数形式。换句话说，Ansible 是“它”，而不是“它们”。

大小写

如果它不是 Ansible 的真实产品、服务或部门，则不要将其大写。即使它看起来很重要，也不要大写。仅将标题中的第一个单词的第一个字母大写。

冒号

冒号通常用于列表或系列之前：- 三角区由三个城市组成：罗利、达勒姆和教堂山。

但如果列表是句子中元素的补语或宾语，则不要使用冒号：- 出行前，请务必（1）设置闹钟，（2）取消报纸，（3）请邻居收取您的邮件。

如果相关列表紧接在“如下”和“以下”之后，请在它们之后使用冒号：wedge 更改目录的步骤如下

打开终端。

输入 cd…

使用冒号来介绍项目符号列表（或破折号，或您选择的图标/符号）

在“属性”对话框中，您将找到以下条目

连接名称

计数

每件商品成本

逗号

使用串行逗号，即三个或更多项目系列中“and”之前的逗号

“项目 1、项目 2 和项目 3”。

这样更容易阅读，也有助于避免混淆。您会发现对此的主要例外是在 PR 中，在那里传统上不使用串行逗号，因为这通常是新闻记者的风格。

逗号始终很重要，考虑到以下两个语句的含义差异很大。

让我们吃吧，奶奶
让我们吃奶奶。

正确的标点符号可以挽救奶奶的生命。

如果这不能说服你，也许这个可以

缩写

不要在 Ansible 文档中使用缩写。

长破折号

如果可能，请使用长破折号，两侧不留空格。当没有完整的长破折号时，请使用双破折号，两侧不留空格 - 就像这样。

一对长破折号可以用作逗号的替代品，以提高可读性。但是，请注意，破折号始终比逗号更强调。

一对长破折号可以替代一对括号。破折号被认为比括号不那么正式；它们也更具侵入性。如果您想引起对括号内容的注意，请使用破折号。如果您想更微妙地包含括号内容，请使用括号。

注意

当破折号用作括号的替代品时，应省略周围的标点符号。比较以下示例。

Upon discovering the errors (all 124 of them), the publisher immediately recalled the books.

Upon discovering the errors—all 124 of them—the publisher immediately recalled the books.

当用作句子末尾的括号的替代品时，仅使用单个破折号。

After three weeks on set, the cast was fed up with his direction (or, rather, lack of direction).

After three weeks on set, the cast was fed up with his direction—or, rather, lack of direction.

感叹号 (!)

不要在句末使用它们。当引用命令时可以使用感叹号，例如感叹号 (!) 命令。

性别代词

不要在文档中使用性别特指代词。阅读使用“他们”和“他们的”而不是“他/她”和“他的/她的”的句子要比阅读使用“他/她”和“他的/她的”的句子舒服得多。

在给出说明时使用“您”，在更一般的解释中使用“用户”、“新用户”等等是可以的。

在撰写技术文档时，切勿使用“one”代替“you”。使用“one”过于正式。

在撰写时切勿使用“我们”。“我们”在用户端没有做任何事情。Ansible 的产品正在按照用户的要求完成工作。

连字符

连字符的主要作用是形成某些复合词。除非有必要，否则不要使用连字符。如果复合形容词不会被误读，或者像许多心理学术语一样，其含义已经确定，则不需要使用连字符。

使用连字符来避免歧义或混淆

a little-used car
a little used-car

cross complaint
cross-complaint

high-school girl
high schoolgirl

fine-tooth comb (most people do not comb their teeth)

third-world war
third world war

在专业印刷材料（特别是书籍、杂志和报纸）中，连字符用于将单词分成一行末尾和下一行开头。这允许在保持一致的右页边距的同时，避免高度变化（并且令人分心）的单词间距。

列表

保持项目符号列表的结构等效且一致。如果一个项目符号是动词短语，那么它们都应该是动词短语。如果一个是完整的句子，那么它们都应该是完整的句子，等等。

将每个项目符号的第一个单词大写。除非很明显它只是一个项目列表，例如：* 计算机 * 显示器 * 键盘 * 鼠标

当项目符号列表出现在其他文本的上下文中时（除非它是一个简单的列表，如前一个示例），请添加句点，即使项目符号是句子片段。这样做的部分原因是每个项目符号都被认为完成了原始句子。

在某些情况下，项目符号独立显示，例如在海报或主页促销中，它们不需要句点。

在给出说明步骤时，使用编号列表而不是项目符号列表。

月份和州

根据 AP 缩写月份和州。月份仅在与日期一起使用时缩写。例如：“总统于 1999 年 1 月访问。”或“总统于 1 月 12 日访问。”

月份：Jan.、Feb.、March、April、May、June、July、Aug.、Sept.、Nov.、Dec.

州：Ala.、Ariz.、Ark.、Calif.、Colo.、Conn.、Del.、Fla.、Ga.、Ill.、Ind.、Kan.、Ky.、La.、Md.、Mass.、Mich.、Minn.、Miss.、Mo.、Mont.、Neb.、Nev.、NH、NJ、NM、NY、NC、ND、Okla.、Ore.、Pa.、RI、SC、SD、Tenn.、Vt.、Va.、Wash.、W.Va.、Wis.、Wyo.

数字

一到九之间的数字写出来。10 及以上用数字表示。例外情况是写“400 万”或“4 GB”。在表格和图表中使用数字也是可以接受的。

电话号码

电话号码样式：1（919）555-0123 x002 和 1 888-GOTTEXT

引号（使用引号和撰写引语）

“把标点符号放在引号里面，”编辑说。

除了极少数情况外，只使用“said”或“says”，因为其他任何东西只会妨碍引语本身，还会倾向于进行编辑。

将姓名放在引号之后，紧随其后: “我喜欢以第一人称写作，因为我喜欢成为我正在写的角色，”Wally Lamb 说。
不是: “我喜欢以第一人称写作，因为我喜欢成为我正在写的角色，”Wally Lamb 说。

分号

如果项目包含逗号，请使用分号分隔系列中的项目

我每天早餐都喝咖啡、吃吐司和水果；午餐吃沙拉；晚餐吃花生酱三明治、饼干、冰淇淋和巧克力蛋糕。

在连词副词（然而、因此、否则、即、例如，等等）之前使用分号：- 我思故我在。

句子后的空格

在句子之后仅使用一个空格。

时间

一天中的时间写成“下午 4 点”。