文档改进

日期:

2018-01-08 22:00

标签:

文档、用户故事、演练

包含您的 Launchpad 蓝图的 URL

当人们使用 openstack-ansible 部署时，常常感到困惑，因为他们只阅读了部分文档，或者进入了错误的文档。

我们的部署指南已经接近我所说的向导/演练，但一些部分很容易被部署者忽略。

此外，一些非常好的高级文档经常被跳过，或者没有得到应有的重视。

问题描述

当人们进入我们的部署指南时，这可能是他们访问的第一个链接，无论他们是从 OpenStack 部署指南 https://docs.openstack.org/pike/deploy/ 还是从我们的主要开发者页面 https://docs.openstack.org/openstack-ansible/latest/ 进入，他们会遇到以下问题

  • 着陆页信息量过大，因为它是一系列链接。 你点击什么？

  • 首先点击的链接（例如：https://docs.openstack.org/project-deploy-guide/openstack-ansible/pike/overview.html#）只是更多地点击内容，并没有提供任何有用的信息（结构已经在页面的左侧显示）。

  • 任何想要快速部署 openstack-ansible 云的人都无法知道我们有一个 AIO 工具包可以提供帮助。

  • 任何想要使用 Netapp 部署生产集群的人，很可能在阅读部署指南时找不到合适的文档：很容易忽略 https://docs.openstack.org/project-deploy-guide/openstack-ansible/latest/configure.html#advanced-service-configuration 上的配置的重要性。

  • AIO 列在“贡献者”指南中，而它应该在任何部署部分都可用。

  • 有一个难以找到的“高级配置”部分，隐藏在操作指南中。 它可能应该成为部署指南的附录。

  • 我们有很多文档重叠，做的事情相同，我们应该清理一下（例如部署 + 操作中的高级配置，操作 + 贡献者 + 参考中的库存）。

  • 部署指南中有太多的附录。 一些应该有自己的部分。 根据规范 https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html，“最终用户内容，例如概念指南、建议、教程、使用 CLI 执行特定任务的逐步说明等。” 我认为我们可以从技术上将场景移动到那里，因为它们是使用 shell 脚本执行某些部署的逐步说明。

  • 角色成熟度难以找到。 如果我是新的部署者，我想知道我可以使用 OpenStack-Ansible 做什么，角色成熟度矩阵将非常有帮助。 可悲的是，我第一次阅读文档时永远不会看到它。

  • 升级指南是我们的用户指南。 为什么不将升级视为一种特定的操作？ 我认为它应该成为操作指南的一部分，作为操作中的一个主要章节，就像次要更新或扩展环境一样。

  • 我们没有激励人们从部署指南直接贡献。 系统工作正常后，最后一步应该是如何扩展和贡献 OpenStack-Ansible。

  • 人们可能会对如何最好地为项目做出贡献感到困惑。

提议的变更

在部署指南的开头添加某种通知，指向我们的用户故事（但建议先阅读部署指南）。 第一个用户故事应该是 AIO，包含快速启动 AIO 内容，适用于那些想要 devstack-like 易用性、开发者或想要原型设计的人。 在用户指南中添加更多用户故事，例如 ceph（测试、生产和 ceph-ansible 集成）、l3 路由场景（测试和生产）、离线安装。

将库存、容器网络、自定义布局和安全原则等高级主题移动到文档的新“参考”部分。 此部分可能应该包含指向角色文档的链接，并且在适当的时候也应该从部署指南链接。

在部署指南中突出显示我们高级主题（参考）的重要性。 新的部署者知道在哪里找到有关如何执行不属于用户指南的 X 的文档非常重要。

在部署指南的末尾，通过指向我们的操作和贡献指南继续部署故事。 这可以添加到下一步骤部分。

贡献者指南也可以通过列出需要帮助的地方来增强：文档（以及它们的手动测试，例如操作指南），bug（分类和修复低垂的果实），测试覆盖率，… 此部分可以在优先级更改时更改。

为了改善阅读体验，确保每个页面都有适当的结构

备选方案

不更改文档，或者部分实施这些更改。

Playbook/Role 影响

无

升级影响

无

安全影响

无

性能影响

无

最终用户影响

无

部署者影响

新的部署者应该对 Openstack-Ansible 的压力更小

开发人员影响

无

依赖项

无

实现

负责人

主要负责人

jean-philippe-evrard

其他贡献者

  • TODO

工作项

所提议更改的每个段落都可以被视为一个工作项。

测试

没有新的内容。

文档影响

这是一个仅限文档的更改，因此整个更改都对文档有影响。 但是，由于我们没有更改文档本身的结构，因此应该不难实现。

参考资料

这些改进只是为了改善我们的可读性，并遵循通常期望在每个文档中找到的内容