DocImprovementsSpec
- Launchpad 条目: https://blueprints.launchpad.net/openstack-devel/+spec/bexar-doc-enhancements
- 创建: 2010-11-29
- 贡献者: AnneGentle
目录
总结
努力产出专业级别的社区化文档。
发布说明
OpenStack 致力于创建由来自世界各地的贡献者协作完成的专业级文档。在本次 OpenStack 版本中，我们希望提供一个文档中心页面，以及官方和经过测试的教程和文档页面的指示。
原理
文档有助于引导新的开发者和部署者上手，并应使他们的 OpenStack 采用过程更加顺畅。文档应提供一个良好的起点，并帮助支持用户在开源云计算领域获得专业知识。
用户故事
作为文档读者，我希望能够以易于理解、可预测、有组织、可浏览的方式查看内容，以便我可以按照自己的节奏从任何期望的入口点浏览内容。
作为文档作者，我希望能够以适合内容集合的方式编写内容，以便我的写作工作能够为用户提供可读的材料。
作为文档作者和读者，OpenStack 文档应与更大的文档交付物相关联，这些交付物可以作为 PDF 或类似的便携式离线可下载集合提供。
作为文档翻译员，我希望为另一种语言（如日语）的作者和读者提供非英语内容。
前提条件
OpenStack 文档集已经包含三个主要站点——wiki 和开发者文档站点。
设计
本节描述了构成此实现设计的各个主要子项目。
文档站点
OpenStack 需要一个中央 docs.openstack.org 站点，该站点可以从各种其他来源整理内容，并在访问时提供良好的用户体验。我的目标是在 Bexar（二月）时实现这一点。
官方文档
OpenStack 需要一种方法来指示页面或站点为“官方 OpenStack 文档”，这意味着它尽可能准确，并且程序已经过测试。我再次将此标记为 Bexar。
版本控制文档
我们正在朝着冻结版本页面/站点迈出小步。例如，您可以访问 http://swift.openstack.org/1.0/ 并获取冻结在特定时间点的站点，其中包含 1.0 版本的开发者文档。我们可以在 Bexar 时完成此操作。
手册页
我们需要为 nova-manage、nova-compute 和 nova-networking 创建手册页。nova-manage 手册页现在包含在构建中，但需要编辑。它来自 doc/source/man 中的 RST 文件，并使用 Sphinx 文档构建。这可以在 Bexar 时完成。
教程
现在我们正在进行虚拟盒子和 stack on a stick 的开发，我们需要有意义且足够简单的教程，以便逐步完成，同时仍然可以令人印象深刻地展示 OpenStack 云的强大功能。以下是一些教程的想法
1) 为 WordPress 等 Web 应用程序创建 LAMP 堆栈 - 演示虚拟机之间的连接，描述博客变得非常流行时如何扩展（嘿，我们可以梦想，对吧？） 2) 构建自己的 CDN 来提供视频内容 3) 使用 Mathematica 项目进行学术计算，仅持续一天或更短时间启动 10 台机器 4) 使用 AMPQ/RabbitMQ 创建新闻阅读器应用程序
我认为我们可以在 Bexar 时完成一个可靠的、经过测试的教程，其余的则留到 Cactus 版本。大家对如何优先处理这些教程有什么想法？哪些需求最高？
Glance 文档
由于 Glance 的实现仍在 Bexar 中进行，我们需要计划与 Bexar 版本一起安装和集成文档。这些文档不需要 openstack.org 的自己的子域，可以驻留在 nova.openstack.org 中。
本地化
OpenStack 在其他国家/地区的日益增长的兴趣需要能够使贡献者翻译现有的英文文档或创建其母语文档的系统。
实现
任务：创建 docs.openstack.org 站点。请参阅 WebContentRequirements 以获取需求和可能的实现工具列表。
任务：创建一个徽章，指示来自 OpenStack 的“官方文档”。
任务：swift.openstack.org/1.0/ 站点已完成，除了左上角链接中的版本号。修复该链接。
任务：创建一个 div，链接到 swift /1.0 站点上的最新文档。
任务：创建一个 nova.openstack.org/2010.1/ 站点。
任务：为 nova/ 2010.1 站点创建一个类似的 div，链接到最新文档。
任务：为 nova-manage 创建一个手册页。已完成，但需要测试。
任务：创建一个 WordPress 优化和扩展教程。与 Martin Lanner 合作提供有关 memcache 和数据库最佳实践的信息。
任务：导入 Glance 的 RST 文档（JayPipes 已起草）并将其合并到 nova.openstack.org 站点中。
任务：在 wiki 中创建第二语言的测试页面。依赖项：用于测试的第二语言系统。
任务：联系日语作者，看看他们是否愿意在 OpenStack wiki 中用日语编写页面。依赖项：通过 Bret Piatt 获取联系信息。
测试/演示计划
无。
未解决的问题
docs.openstack.org 引擎的选择尚未确定，但它是计划的一部分。
