OpenStack 文档贡献者指南¶
https://blueprints.launchpad.net/openstack-manuals/+spec/docs-contributor-guide
问题描述¶
基于文档贡献者的经验和反馈，wiki 上现有的文档贡献者信息有时包含过时的信息，可以通过重构和补充来改进。
由于我们将文档视为代码，并希望其他人也能这样看待，我们需要将所有约定、操作说明以及任何与文档贡献者相关的内容迁移到适合作为单一入口、完整且整洁的指南的位置，该指南能够解答文档创建工作流程中出现的问题。
wiki 显然不太方便，其功能有限，并且缺乏许多现代互联网用户认为必不可少的功能，例如搜索、适当的导航等。
调整内容不会影响其对社区的开放性，也不会使约定变得不灵活。这只会统一和简化流程。
提议的变更¶
我们建议创建文档贡献者指南，面向 OpenStack 文档的贡献者，内容涵盖
- 工作流程（= 快速入门）
- 工作流程（= 操作指南）
- 许可和版权声明 - 包含指向以下链接的概要
- 标记约定（RST - 首要优先级，DocBook）
- 术语和写作语法约定
- 截图和拓扑约定
- 文档结构
- 团队结构
文档贡献者指南：RST
以下表格列出了现有的 wiki 内容，并概述了从贡献者角度应该如何重构这些内容
| Wiki 页面 | 用户故事 |
|---|---|
| 操作指南 | 作为文档贡献者，我希望详细了解：需要哪些工具；如何编辑、检查构建并提交更改；如何修改正在审核的内容、cherry-pick 并对稳定分支进行更改；如何处理 launchpad bug 并审核补丁。 |
| HowTo/FirstTimers | 作为文档贡献者，我希望有一个快速入门指南，其中包含一套基本的关于如何提交更改、响应请求和排除故障的说明。 |
| Documentation/Builds 和 Documentation/ContentSpecs | 作为文档贡献者，我希望清楚地了解哪些内容应该放在哪里，以及在哪里获取源代码（+ 为什么需要规范以及如何创建它）。 |
| Documentation/Conventions | 作为文档贡献者，我希望了解所有贡献者在贡献 OpenStack 文档时应遵循的写作风格指南。 |
| Documentation/Markup_Conventions | 作为文档贡献者，我希望了解所有贡献者在贡献 OpenStack 文档时应遵循的 XML/RST 标记指南。 |
| Documentation/JSON_Conventions | 作为文档贡献者，我希望了解所有贡献者在贡献 OpenStack 文档时应遵循的 JSON 指南。 |
| Documentation/Structure | 作为文档贡献者，我希望了解如何在书籍中命名和安排文件和目录。 |
注意
HowTo 和 HowTo/FirstTimers 也包含在 https://docs.openstack.org/infra/manual/developers.html 中。我们不应该重复，而应该在那里引用它。
实现¶
工作项¶
- 创建一个单独的 wiki 页面来保存项目的所有相关详细信息。
- 在 wiki 上制定详细且结构良好的目录。
- 在 openstack-manuals 中创建并调整一个单独的目录用于该指南。
- 修改、移动和删除现有的（wiki）内容。
- 创建新的内容，这些内容是从贡献者角度需要的，例如，截图和拓扑指南。
- 确保不要重复 https://docs.openstack.org/infra/manual/developers.html 中的内容，但如果需要，请引用它。
- 将文档贡献工作流程的链接添加到 Infra 手册中。
负责人¶
- 主要负责人
- Olga Gusarenko, ogusarenko
其他贡献者
- Alexander Adamov, aadamov
- Olena Logvinova, ologvinova
- Maria Zlatkova, mzlatkova
测试¶
来自文档贡献者的反馈
参考资料¶
- 添加指向项目 wiki 页面的链接。
除非另有说明，本文档根据 知识共享署名 3.0 许可协议 授权。请参阅所有 OpenStack 法律文件。