改进手册中词汇表的用法¶

问题描述¶

OpenStack 是一个大型项目，具有许多不同的组件和用例。人们在尝试设置 OpenStack 时遇到的一个主要问题是，有太多的活动部件和不同的用例。尝试部署、配置和使用 OpenStack 的人不一定熟悉所有组件、技术或与 OpenStack 相关的术语。

OpenStack 手册附带一个词汇表，其中提供了许多这些术语的定义。然而，手册中对这个有用资源的引用相对较少，因此用户/部署者可能不知道词汇表的存在，并花费时间查找这些新术语，然后才将其还原到 OpenStack 的语境中，而这对于他们来说可能是一个新的概念。这可能导致 OpenStack 被认为难以掌握，并且上手困难。

提议的变更¶

拟议的更改将向手册中的词汇表术语添加链接，以便用户可以轻松访问在 OpenStack 上下文中不熟悉的术语的描述。这样可以改善用户体验，并使他们能够比必须查找术语并弄清楚它如何关联/在 OpenStack 中使用时更快地理解 OpenStack 术语。

此过程包含两个步骤（以及多个子步骤）

• 删除缩略语/通用术语
• 将词汇表中的术语链接到书籍

步骤 1：删除缩略语/通用术语

第一步是从词汇表中删除不必要的术语。为了实现这一点，我们需要确定哪些是不必要的术语。这可能需要花费大量时间进行审查。就拟议的删除而言，建议的方法是

• 确定删除标准
  • 缩略语

  • 通用术语（词汇表中定义的术语应包括它们如何

    与 OpenStack 相关）

• 为每个标准集合按字母顺序提出补丁：- 例如 [glossary] 删除缩略语 [A-B]

缩略语 是最容易开始的地方。

缩略语不应有自己的定义，而应作为相关条目的组成部分。

# Good entry, the commonly used acronym is included in the entry heading
IP Address Management (IPAM)
The process of ....

# this entry is bad because it just expands the acronym
IPL
Initial Program Loader.

通过第一个测试的条目不一定能通过第二轮，但它可以保持内容在重构时的整洁。

对于确定要删除的通用术语，必须定义有效的术语。任何不符合有效标准术语的术语都可供删除。

一个 有效术语 是

• OpenStack 特有的，例如 租户、项目、计算节点

  在 OpenStack 之外不存在或以不同方式使用的术语。

• 项目的代号，例如 nova、neutron、keystone

  在这种情况下，代号是条目，而不是服务

  # This is an unnecessary entry, because the term readers would be looking
  # for is Trove, not database service
  Database Service
  ... The project name of Database service is trove.
  

  • 在大多数情况下，服务名称/代号可以合并到一个更大的条目中。

• 在 OpenStack 的使用上下文中定义的通用术语

• 受支持的技术无效，因为这将在手册中提及时显而易见（驱动程序也是如此）

  • 例外：以非标准方式使用该技术

• litmus 测试：互联网搜索会返回相同的信息吗？

  # Bad - technology used in OpenStack, in a standard way
  SQL-Alchemy
  An open source SQL toolkit for Python, used in OpenStack.
  

步骤 2：将词汇表中的术语链接到书籍

此更改的第二部分是确保使用词汇表。此步骤将手册中的相关术语链接到词汇表条目。可以按本书为基础进行操作，如下所示（具体取决于书籍的大小和术语的数量）

• 迭代词汇表中的术语，并确定它们是否在本书中使用

• 将术语分组为可管理的块

  [glossary] admin-guide links [A-D]
  

• 章节中的第一个出现应该链接

审查流程

为了便于审查，每次都提出一组更改以供删除。如果存在任何有争议的术语，这些术语将从主要审查中删除，并单独提出，以便可以尽快完成大部分工作，并且不会因为对异常术语存在强烈意见而受阻。

实现¶

依赖项¶

无

测试¶

不需要额外的测试。

已经存在检查词汇表术语是否存在的功能，可用于确保没有无效链接。

参考资料¶

邮件列表主题

http://lists.openstack.org/pipermail/openstack-docs/2016-July/008915.html