基本规则

使用标准美式英语

Ansible使用标准美式英语。注意美式英语中拼写不同的常见单词(例如color vs colour,organize vs organise等)。

面向全球受众写作

您所说的所有内容都应该让不同背景和文化的人都能理解。避免使用习语和地区性表达,保持中性语气,避免误解。避免尝试幽默。

遵循命名约定

始终遵循命名约定和商标规则。

使用清晰的句子结构

清晰的句子结构意味着:

  • 首先陈述重要信息。

  • 避免添加使句子难以理解的冗余词语。

  • 保持简洁 - 较长的句子更难理解。

一些改进句子的示例

糟糕的例子

在悬崖边缘附近行走的人可能会发生危险的坠落,因此建议保持安全距离以确保人身安全。

更好的例子

危险!远离悬崖。

糟糕的例子

此外,该提取过程还需要大量的用水。

更好的例子

提取过程也需要大量的用水。

避免冗余

写简洁的句子。避免使用以下术语:

  • “…如前所述,”

  • “…每一个,”

  • “…某个时间点,”

  • “…为了…”

突出显示菜单项和命令

在编写菜单或命令文档时,使用粗体突出显示重要内容。

对于菜单步骤,请将菜单名称、按钮名称等加粗,以帮助用户在GUI中找到它们。

  1. 文件菜单上,点击打开

  2. 用户名字段中输入名称。

  3. 打开对话框中,点击保存

  4. 在工具栏上,点击打开文件图标。

对于代码或命令片段,请使用RST code-block指令

.. code-block:: bash

  ssh [email protected]
  show config