2017/2018 文档团队愿景

目标

将我们愿景流程的各个部分整合到一份单一文档中，以便在未来 12 个月内设定目标。

注意

本文档是从未来主义的角度撰写的。

背景

在女王镇 PTG（项目团队会议）期间，OpenStack 文档团队概述了我们流程中需要改进的四个关键领域。这些领域包括记录用例、设定期望、提高内容可见性和贡献文档。

回顾过去一年，我们在所有四个领域都取得了积极进展。虽然仍有许多工作要做，但我们有很多值得骄傲的地方！

用例

与文档团队合作，OpenStack 基金会建立了一个新的贡献者门户网站 (openstack.org/community)，它为感兴趣的用户类型（例如操作员、用户和贡献者）提供了一个自主选择的冒险之旅。用户选择他们感兴趣的活动类型，并能够快速导航到相应的文档。

此外，还提供了一组新的高级通用用例文档（例如，如何使用 Gerrit 以及如何注册项目），其中详细介绍了与 OpenStack 社区集成的常见任务的逐步说明。这使得在上次用户调查中，OpenStack 文档及其对社区的有效性方面有所净增长。

OpenStack 文档团队与大多数项目团队在下一个 PTG 地点的秘密名称处会面，以提供有关开发基于主题的文档的帮助和指南，这些文档具有 OpenStack 项目的高级描述，并由逼真、跨社区和结果特定的用例支持。用例在所有项目中保持一致，遵循统一的信息架构。

项目首先提供至少三个定义的用例，然后他们为用例开发内容，并将用例签入到项目的存储库中。文档团队通过审查最受欢迎的用例的统计数据来衡量成功，并计划在下一个周期中添加更多内容来支持它们。

设定期望

在过去一年中，我们收到了来自贸易媒体或分析师社区对 OpenStack 文档质量的三次积极评价。项目团队拥有并维护自己的内容，并与 i18n 团队合作，以确保文档可翻译。项目团队通过其项目联络员，遵循文档团队建立的流程来定义用例。项目存储库中的每个代码提交都包含文档（如果适用）。我们成功地在发布日历中添加了一个窗口，用于与每个项目联络员进行一组内容审查，具体取决于项目的需求。项目团队在管理其内容时遵循更新的治理文档 标签指南。

内容可见性

在最后一个开发周期中，文档团队能够通过改进搜索引擎优化 (SEO) 和内容塑造来提高搜索引擎结果。根据 Google Analytics 定义的最常见搜索词正在返回及时且相关的结果，并正确地指向 docs.openstack.org 上的相应文档。

为了解决新用户和潜在用户的问题，文档团队与 OpenStack 基金会、OpenStack Wiki 团队和 ask.openstack.org 合作，以在我们的所有资源中创建一致的沟通，以确保用户被正确地引导到新的贡献者门户网站或 docs.openstack.org 上的特定项目的文档。在过去一年中，我们的成功指标显示 COA 考试参与者和用户调查评论中的积极响应增加了 10%。此外，docs.openstack.org 的流量增加了（> 20%），这表明社区对其利用率更高。

最后，为发布实施了更全面的文档 归档生命周期。归档内容仍然可供需要它的用户使用，但我们添加了 CSS 叠加层以帮助避免混淆，并确保在查看旧内容时清晰明了。这解决了 COA 考试参与者和使用旧版本且无法访问旧文档的操作员报告的问题。

贡献文档

文档团队与 Upstream Institute 合作，以帮助改进针对新贡献者的指导和培训。文档团队设计了一套培训材料，为 Upstream Institute 志愿者导师提供指南。在 OpenStack Summit 和 PTG 期间，选择了两名导师与新贡献者小组合作，此外还有在 Summit 上举办的入职培训。导师鼓励新贡献者利用他们对项目团队的新知识，积极地将文档贡献回各自的项目团队。