Mitaka 的用户指南重组

更新日期：2018-12-06 13:55

Mitaka 版本的用户指南重组¶

编辑云管理员指南、管理员用户指南和最终用户指南，以确保内容支持管理员、最终用户和云管理员。

问题描述¶

在 Liberty 周期中将这些指南转换为 RST 格式后，现在可以重新组织它们的内容，以提高一致性并减少重复内容。

评估当前内容的关联性和准确性，并改进指南之间的链接，以便处理类似的任务和概念。

提议的变更¶

编辑内容以消除风格上的不一致性和内容上的不准确性

清理现有内容，进行语法检查、冠词的使用以及主谓一致性检查。

统一指南中表格的一致性——调整为带有粗体标题的变量列表，或在单元格内使用 `:code-block:` 角色来突出显示命令的表格。

将故障排除部分重新组织为单一格式——将故障排除部分更改为使用块存储章节中使用的“问题”和“解决方案”格式。

使用用户任务矩阵和 OpenStack 基金会管理员调查的结果，明确每个指南的受众。相应地重新组织内容。
通过将管理员用户指南的内容合并到云管理员指南中来重构指南。从 openstack-manuals 中删除管理员用户指南。
合并内容后重命名云管理员指南。将文档标题更改为“管理员指南”。
从 openstack-manuals 中删除 Python SDK 源代码文件，将文件移动到 api-site，并在 developer.openstack.org 上发布。当前已发布的文件位于 https://docs.openstack.org/user-guide/sdk/html，源代码位于 http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/user-guide/source/sdk*.rst

备选方案¶

仅实施第一个和第二个建议的更改，保留三个独立的指南。
仅实施第一个建议的更改，并按照描述的方式编辑内容。
不进行任何更改，保持指南的原样。

实现¶

负责人¶

Joseph Robinson(joseph-r-email)

Brian Moss(kallimachos)

其他贡献者¶

用户指南团队以及任何愿意测试程序准确性或校对指南的人员。

联系当前未在指南中列出的团队负责人，讨论哪些任务和操作对管理员指南最有用和最需要，并确认术语表项目：Designate、CloudKitty、Magnum 和 Zaqar。

工作项¶

工作项按云管理员指南的章节细分。

身份管理¶

用户 CRUD：在管理员用户指南中包含信息和简要的执行此操作的步骤。
启动身份服务：将此内容移动到另一个部分，以减少存储库中的文件数量。
使用身份进行外部身份验证：身份服务中的另一个较小的部分可以合并。

仪表板¶

检查 Liberty 仪表板更新和更改。

计算¶

AMPQ：使用冒号介绍列表。将括号中的缩写大写——将 (ampq) 更改为 (AMPQ)。
虚拟机监控程序：重新组织并链接到管理员用户指南。包含有关如何使用虚拟机监控程序的部分。
租户、用户、角色：删除被动语态。链接到最终用户指南的“我如何使用云？”部分 *管理员用户指南*——创建和管理角色——重新组织此内容，使其与云管理员指南的内容保持一致。

EC2 兼容性¶

删除被动语态。
将此部分与 Liberty 安装指南进行比较。

构建块¶

简介：明确此处指的是哪个基本操作系统。检查内容是否准确。
nova image-list 命令。将 nova 命令行客户端的内容与此处最终用户指南中的内容链接在一起。

镜像和实例¶

使简介与最终用户指南保持一致。
使启动实例和添加和删除资源部分与管理员用户指南保持一致。
“此图显示启动实例之前的系统状态”描述图的各个部分。该段落不清楚。扩展到其他图的修改。

使用 nova-network 进行网络¶

改进故障排除部分，如近期对用户 nova-network 到 neutron 采用和迁移的研究所示。
云管理员指南引用了用户可以更改的浮动 IP 地址。用户指南中关于网络的章节需要重新组织，以与此内容保持一致。还需要测试有关将 IP 地址分配给 VM 的信息。
VLAN 网络管理器：检查段落缩进。
nova network-create vmnet：统一指南中表格的一致性。
配置计算以使用 IPv6 地址：统一指南中表格的一致性。

元数据¶

Liberty 到 Mitaka-元数据服务现在包含“project_id”，具体内容参见发布说明。
元数据需要专家进行检查以确保时效性。（Andrew Bogott、John Garbutt、Matthiew Gagne）
元数据配置选项表说明：统一指南中表格的一致性。

风味¶

风味定义这些元素表：地址表一致性问题。（此处使用粗体标题和句子）。
管理员用户指南中设置风味表格是否有效？
显示主机使用情况统计信息：主机使用情况统计信息说明，并更改为粗体标题。

使用 Rootwrap 进行保护¶

配置选项 [默认值]：专家进行检查，并更改为更好的格式。可能需要代码片段
迁移实例：这些表格是代码片段。是否可以用图像或适当的代码片段替换它们？
VNC 配置选项：包含 VNC 配置选项的说明
常见问题解答：指南中的常见问题解答与其它信息冲突。
需要在此处进行信息架构检查，以重新处理此信息。
安全加固：改进使用可信计算池的 OpenStack 的第二个图。需要标题和与其他图一致性。
灾后恢复云：测试或请专家检查此过程。

对象存储¶

用户指南：创建和管理对象容器部分需要来自云管理员对象存储部分介绍的内容。“...对象存储（代号 swift 是用于使用集群创建冗余、可扩展数据存储的开源软件...”
对象存储特性——没有提及容器，但用户指南提到了这个术语。编辑以保持一致性。
组件：编辑被动语态的使用，并调整介绍组件的开头句子。将描述性开头句子移动到简介中，以及云管理员对象存储部分。
环：在环图下方，编辑这些句子以解决逗号拼接问题。
区域：提及高可用性以及组件部分中已提及的其他组件。因此，不需要组件描述。编辑以消除重复。
分区：编辑标点符号——逗号拼接
更改块存储章节中的集群架构和环构建器部分。
帐户回收器：“在后台，帐户回收器会删除已删除帐户的数据……”编辑此处的语法。
对象存储监控——摘自博客。保留还是删除？本节还需要语法审查。

块存储¶

块存储：持久存储需要在本简介中更早、更清楚地提及。
迁移卷：这些命令可以出现在最终用户指南中
块存储命令行列表：“cinder-manager host lists”、“cinder get-pools”适应管理员用户指南。
备份和恢复卷：此过程是云管理员过程，还是可以将基本信息改编到管理员用户指南中？需要明确角色。
澄清管理员用户指南中的传输卷部分是否与云管理员指南中的导出和导入备份元数据过程类似。
配置和使用卷数量称重器：此过程引用了最终用户指南和云管理员指南中描述的 cinder 命令。重新组织此内容。
过滤器和良好函数中支持的操作：删除警告说明中的被动语态。
限制卷复制带宽：重新组织指南，以便此内容出现在有关移动和迁移块存储卷（“volume_copy_bps_limit”）的信息附近。
镜像卷缓存：删除被动语态。
获取功能：本节描述了管理员可以使用 API 执行的操作，功能调查。将此信息与管理员用户指南一起重新组织。
多路径调用失败退出：此故障排除部分采用问题和解决方案标题架构，该架构对云管理员指南的其他故障排除部分很有用。

共享文件系统¶

关键概念：删除被动语态。
共享基本操作：“常规概念”编辑或澄清此短语。
Manila 命令 show、update 和 delete 选项可以出现在管理员用户指南中。明确共享文件系统的职责。
管理和取消管理共享：编辑某些句子中缺失的单词
调整共享大小：此处也缺少单词。
配额和限制：编辑主谓一致性。
共享快照：在此处包含管理员用户指南中列出的 manila snapshot-create 命令。
一致性组：编辑主谓一致性（“admin to admins”）。
调度：编辑冠词和定冠词。
网络——编辑缺失的单词。
共享网络——编辑主谓一致性

网络¶

插件配置部分：记录最常见的 ml2 插件配置。
ml2 的参考网络选项插件 https://docs.openstack.org/liberty/config-reference/ content/networking-options-plugins-ml2.html。请参阅 https://bugs.launchpad.net/openstack-manuals/+bug/1411624
使用网络部分：网络表格需要与云管理员指南中的其他表格保持一致。
网络架构：本节对架构的描述最好放在简介之后。
将身份配置为网络：此处有一个关于不要将 Nova-network 与计算一起使用的注释，但需要在简介中更早出现——作为云管理员的警告。

数据库¶

目前没有推荐的更改。

裸机¶

目前没有推荐的更改。

编排¶

目前没有推荐的更改。

遥测¶

数据检索：代码片段表格需要适应页面。
测量：确认没有从 Liberty 版本添加其他测量项目。

编排¶

编排授权模型：本节需要进行语法编辑。
堆栈域用户：本节也需要语法编辑。
跨域资源共享：子部分“通过配置启用 CORS”需要进行编辑，以更改为过程而不是项目列表。

跨项目功能¶

目前没有推荐的更改

重定向和构建作业¶

文件重定向和执行构建作业也需要完成。

项目范围¶

OpenStack 的项目导航器描述了项目成熟度。项目导航器页面上列出的统计信息涵盖项目年龄、采用率、稳定分支存在情况、公司多样性、SDK 支持和安装指南内容。
符合这些统计信息中的多个统计信息的 OpenStack 项目包括 Nova、Neutron、Swift、Cinder、Keystone、Glance、Horizon 和 Heat。本次重组将改进指南中这些服务的相关内容，但不会进行大规模更改。
仍在寻求更多成熟度指标的、可能开发时间不超过三年的较新开发项目包括 *Zaqar*、*Murano*、*Sahara* 和 *Trove*。 *Manila* 内容需要关注，如共享文件系统部分下的工作项所述。本次重组的范围还包括来自这些较新项目的相关内容。引入或改进来自较新项目的新的内容是本次重组的大规模更改。

依赖项¶

测试¶

需要对 Devstack 环境和 OpenStack 测试安装中的网络和核心服务进行一些测试。

参考资料¶

讨论可以使用任何官方渠道进行，包括 #openstack-doc IRC 频道、主题中包含 [用户指南] 的 openstack-docs 邮件列表、每周用户指南专项小组会议、每周文档团队会议，以及任何进一步的工作项的笔记可以记录在用户指南 Etherpad 中。