通用写作指南

请遵循以下指南，以确保 OpenStack 文档的可读性和一致性。

使用标准英语

在所有技术出版物中使用标准美国（U.S.）英语。如有疑问，请查阅 Merriam-Webster’s Collegiate Dictionary 和 IBM developerWorks 编者风格指南。

使用主动语态

通常，使用主动语态而不是被动语态。主动语态将动作的施动者作为动词的主语——通常是用户。被动语态将动作的接受者（而不是来源）作为动词的主语。

主动语态的句子可以明确动作的执行者，并且比被动语态的句子更容易理解。被动语态通常不如主动语态吸引人，而且更复杂。当您使用被动语态时，软件的动作和响应可能难以与用户的动作和响应区分开来。此外，被动语态通常需要比主动语态更多的词语。

用例示例

不要使用

使用

在安装完软件后，可以启动计算机。

安装完软件后，启动计算机。

单击 OK 后，配置将被保存。

单击 OK 以保存配置。

服务器由您创建。

创建服务器。

但是，在以下情况下可以使用被动语态

  • 使用主动语态听起来像是责怪用户。例如，您可以在错误消息或故障排除内容中使用被动语态，当主动语态的主语是用户时。

    用例示例

    不要使用

    使用

    如果构建失败，您可能省略了 flavor。

    如果构建失败，flavor 可能被省略了。

  • 动作的施动者未知，或者您想淡化动作的施动者并强调动作作用的对象。

    用例示例

    不要使用

    使用

    产品、操作系统或数据库返回消息。

    消息由 [数据库] 返回。

  • 将句子改写成主动语态会显得冗长或笨拙。

    用例示例

    不要使用

    使用

    2009 年，工程师开发了一种简化安装的软件。

    一种简化安装的软件于 2009 年开发。

使用一般现在时

用户阅读文档以执行任务或收集信息。对于用户来说，这些活动发生在他们的现在，因此在大多数情况下使用现在时是合适的。此外，现在时比过去时或将来时更容易阅读。

只有当您需要强调某事稍后会发生（从用户的角度来看）时，才使用将来时。

用例示例

不要使用

使用

该产品将提示您验证删除操作。登录后，您的帐户将开始验证过程。

该产品提示您验证删除操作。登录后，您的帐户将开始验证过程。

使用第二人称

当您使用第二人称（即，将用户称为“您”）时，用户会更投入文档。

使用第二人称具有以下优势

  • 第二人称通过直接称呼用户来营造友好的语气。

  • 使用第二人称和祈使语气（其中主语您是隐含的）以及主动语态有助于消除冗余和关于谁或什么发起动作的困惑，尤其是在程序步骤中。

  • 使用第二人称还可以避免使用具有性别特性的第三人称代词，例如他、她、他的和她的。如果您必须使用第三人称，请使用代词他们和他们的，但请确保代词与所指的名词在数量上匹配。

谨慎使用第一人称复数代词（我们、我们的）。这些代词强调作者或 OpenStack 而不是用户，因此在使用它们之前，请考虑第二人称或祈使语气是否更“用户友好”。但是，使用“我们建议”而不是“建议”或“OpenStack 建议”。

如果需要，您也可以用“我们”代替 OpenStack。

不要使用第一人称来避免命名产品或避免使用被动语态。如果产品正在执行操作，请使用第三人称（将产品作为执行者）。如果您想淡化动作的施动者并强调动作作用的对象，请使用被动语态。

第一人称单数代词“我”可以在常见问题解答的问题部分以及当博客或署名文章的作者描述自己的行为或观点时使用。

不要在同一文档中切换人称（视角）。

用例示例

不要使用

使用

创建服务器涉及指定名称、flavor 和镜像。

要创建服务器，用户需要指定名称、flavor 和镜像。

要创建服务器，请指定名称、flavor 和镜像。

要创建服务器，您需要指定名称、flavor 和镜像。

使用适当的情态

对于程序，使用祈使语气。

示例

通过按 Enter 键开始安装。

对于解释，使用陈述语气。

示例

该脚本会自动使用所有必需的设置配置虚拟机。

不要使用虚拟语气。

用例示例

不要使用

使用

如果您要部署 OpenStack…（隐含：但您没有）

如果您想部署 OpenStack…

保持句子简短

简短而简单的句子更容易阅读和理解。

避免含糊不清的标题

每个标题应包含对页面主题的清晰描述。

含糊不清

更好

更新元数据

更新 flavor 元数据

此外，请确保您遵循文档标题指南。有关更多信息，请参阅 标题。

清晰简洁

遵循极简主义原则。如果您可以用一个词来描述一个想法，就不要使用两个词。消除所有冗余修饰语，例如形容词和副词。

客观写作

不要使用幽默、术语、感叹号、习语、隐喻和其他口语化表达。

首先描述最常见的用例

将最常见的用例放在主要子句和段落或章节的开头。您可以通过以“但是”或“如果”开头来介绍其他用例。

不要将无生命物体拟人化

不要赋予非人类主体或对象人类特征。

用例示例

不要使用

使用

本指南假定

本指南描述

积极写作

以积极的语气写作。积极的句子可以提高可读性。尽量避免以下词语

用例示例

不要使用

使用

损坏

影响

灾难性

严重

糟糕

使用“严重”或添加解释

失败

无法

杀死

取消

致命

严重

摧毁

删除

错误

不正确、不一致

避免句子末尾使用介词

尽可能避免句子中出现尾随介词，方法是避免使用短语动词。

用例示例

含糊不清

更好

图像注册窗口将打开。

图像注册窗口打开。

要修复动词-介词结构，请用主动动词替换它们。

用例示例

含糊不清

更好

写成

组成

弹出

出现

不要过度使用 this、that、these 和 it

谨慎使用这些代词。过度使用会导致读者感到困惑。要修复歧义，请重新措辞句子。

用例示例

含糊不清

更好

监控系统应定期执行检查，以验证 Ceph 集群是否正常。可以使用 Ceph health 命令实现此目的。

监控系统定期执行检查，以确保 Ceph 集群正常运行。使用 ceph health 命令运行健康检查。

您还可以通过在代词后立即放置名词修饰语来修复歧义。

不要拆分不定式

不要在“to”和动词之间放置修饰语。通常，在“to”和动词之间放置副词或形容词会给句子增加歧义。

但是，在某些情况下是可以接受的。

示例

为了显著改善…

避免拟人化

不要在技术写作中表达您的恐惧或感受。避免使用副词，例如“可能”、“希望”、“基本上”等等。

不要使用缩写

通常，不要缩写单词。

用例示例

不要使用

使用

can’t

cannot

don’t

do not

消除不必要的礼貌

不要在技术文档中使用“请”和“谢谢”。

使用一致的术语

在整个 OpenStack 内容中使用一致的术语。避免使用多个变体或拼写来指代相同的服务、功能、UI 元素等等。

用例示例

不要使用

使用

防火墙即服务

防火墙-即-服务

主动-主动

主动/主动

模块

服务

如果您怀疑该主题之前已被描述，请搜索 OpenStack 文档并查找先例。

使用拼写和语法检查工具

如果可用，请将文本通过拼写和语法检查工具。更正错误，尤其是针对大量新内容，有助于消除后续的返工。