本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- 欧洲核子研究中心 (CERN-HSF)
- 技术文档工程师：
- 阿里亚德尼
- 项目名称：
- Rucio - 对 Rucio 文档进行现代化改造（重构和重写）
- 项目时长：
- 标准时长（3 个月）
Project description
摘要：Rucio 框架的开发目标是管理和组织不同结构的数据中心内分布在不同地理位置的大量科学数据。该框架提供分布式数据恢复和自适应复制等功能，具有高度的可伸缩性、模块化和可扩展性。此类服务文档的使用者来自不同的背景，对访问的要求也各有不同。因此，此类服务的良好文档应该有助于简化最终用户的采用和使用，同时还能作为常见问题和问题排查的参考。
如果没有此类文档，有效利用就会面临重大阻碍。这可能会增加支持成本，并给产品的企业身份带来声誉风险。毕竟，文档是一种沟通模式。因此，应确保将沟通封装在一个易于管理且可访问的框架中，同时通过适当的版本控制保持相关性，从而确保传达成功。
在撰写本文时，Rucio 框架已经用来满足 LHC 的 ATLAS 和 CMS 实验的高能要求。除此以外，我们还将这些数据用于支持天体物理学之外的各种科学界的需求，从而使文档内容尽可能相关且易于访问。CERN 希望通过一个集中视图访问所有相关文档，使 Rucio 的最终用户能够在使用该框架的同时获得无缝体验。
现状： 截至今天，用户文档遍布不同的地方，并有多种格式，包括科学文章、readthedocs.io （包含源代码）、Google 云端硬盘、GitHub、DockerHub 或 Wikis。多个来源会给跟踪版本和文档的正确性带来问题。此外，对于给定用例，分散的文档模型在导航和显示相关信息方面存在重大障碍。为特定实验提供的信息完全适用于同一/其他来源的其他实例，尤其是在 Wiki 中。然而，由于缺乏整合和适当的关联，这些信息处于休眠状态，并且有可能未被充分利用。
为什么您提议的用户文档比当前文档有改进？ 鉴于问题涉及多个方面，下面提出的模型消除了导航、版本控制、跟踪和文档显示方面的障碍，具体说明如下：
调整文档结构是为了简化最终用户导航工作量。他/她在搜索信息时无需下洞，因为为简单起见，我们会对其进行分类/标记。从管理角度来看，版本控制和跟踪变得非常简单，因为通过调整结构，您可以根据要求自由分类。 将所有经过重组的文档集中起来，以确保用户可以看到所有信息，而不必引用多个来源。
分析： 阅读完要求简报并与指导团队对话后，我对 Rucio 文档的当前状态进行扣减如下：
文档有六个主要来源： - Google 云端硬盘链接：https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Readthedocs 由 Sphinx 提供支持，代码中包含源代码 代码链接：https://github.com/rucio/rucio ReadtheDocs 链接：https://rucio.readthedocs.io/en/latest/
DockerHub 链接：https://hub.docker.com/u/rucio
GitHub 链接：https://github.com/rucio/rucio
Wikis 链接：https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
科学文章链接：https://arxiv.org/abs/1902.09857
这些来源提供的文档采用不同的格式。例如，Google 云端硬盘拥有幻灯片和 Google 文档形式的文档，GitHub 中的文件主要采用 reStructuredText 标记语言等。缺少版本控制和跟踪功能，会导致在多个来源上发布多余的信息。 信息的标记/分类不统一。因此，您在进行搜索时需要具备相关经验和专业知识。
鉴于格式和来源多种多样，我们希望重新调整信息结构，并使用 mkdocs 将其集中到一处。为了更好地了解这些工具，我研究并熟悉了这些工具的使用方式。
认定结果： 现有文档结构杂乱且分散，没有适当的链接。此外，它在格式方面缺乏集中性和统一性。这会导致用户不得不花费额外的精力来进行搜索。这种差距还会给管理员/维护人员/潜在客户带来不必要的压力，因为很难维持由社区推动的方法来维护和更新文档。用户和贡献者的体验会大大降低，并且还会重复
所提议文档的结构：在对要求进行全面分析后，我决定通过重构的文档解决主要痛点。
下文所附模型演示了这一经过重组的模型。该模型会将每个文档分为以下 7 类：
- 简介
- 使用入门
- 概念
- Rucio 界面
- 待办事项
- 教程
- 高级知识
当然，我们也有一些改进措施，例如添加一些链接，我想在完成此计划后添加这些链接。由于有超过 1000 名活跃用户在 Rucio 上访问 500 PB 的数据，因此提议重新调整其文档结构应该可以显著减少用户寻求帮助邮件列表的需求。其目标是通过降低点击率，以及通过分类和标签轻松展示文档，从而改善用户体验。您可以从用户/运营/管理员的角度了解所有信息，只需点击 3 次或更少操作即可查看这些信息。
模拟链接：https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)
项目目标： - 分析并剪除各种来源的冗余信息，即每条信息都应有一个可信来源。 - 通过为现有文档添加标签并进行归类来调整结构 - 将调整后的文档迁移到基于 mkdocs 的集中视图 - 重新设置由于文件格式限制而无法迁移的文档的格式/导入文档 - 设置社区推动的文档修改，以确保在关联、信息更新或错误更正方面弥补任何缺失的缺口。
该系统的基本框架已经就绪，不过，我的模型通过适当的文档为贡献和治理制定合适的准则，从而对现有系统进行改进。此外，我设想整合 GitHub 项目板，以跟踪项目的问题和总体运行状况。
时间表： - 8 月 16 日之前 --> 熟悉当前版本和 Rucio --> 了解在项目期间会很有帮助的新技术和技术写作技能 --> 为 GitHub 上报告的文档问题（如有）贡献力量
社区凝聚力（8 月 17 日 - 9 月 13 日） --> 设立沟通渠道和时间来考虑不同时区的差异（普内岛提前 3 小时 30 分钟） --> 明确目标优化的主要痛点 --> 通过参与对话详细了解社区、组织和框架。 --> 与导师及组织的其他关键成员一起评估建议的文档结构，确保实施的可行性和可行性。 --> 最终确定建议的功能以及可能需要对现有文档进行的任何其他修改。
记录期（9 月 14 日至 11 月 30 日） 根据我在这里制定的提议格式，我详细说明了计划在记录期内实现的主要里程碑。
--> 里程碑 1：分类和标签 ETC：2020 年 9 月 28 日 整合可用文档并为其添加标签可以极大地简化重组和删减过程。
--> 里程碑 2：分析、剪枝和结构调整 ETC：2020 年 10 月 19 日 将分析在里程碑 1 中对在里程碑 1 中分类的文档，找出重复信息和冗余信息来源。正如项目信息中所述，我们希望所有可用信息都是一个可信来源。
--> 里程碑 3：集中化和重新设置格式： ETC：2020 年 11 月 9 日 在对文档进行适当删减和调整后，我会尝试先重新设置其格式。由于来源不同，格式也不同，首先需要将其转换为适当的格式。完成后，集中处理过程就容易多了。
--> 里程碑 4：设置跟踪委员会和有关治理/贡献的文档 ETC：2020 年 11 月 23 日 此阶段是为了确保项目完成后，文档会持续更新。制定准则并建立项目委员会可减轻行政人员征求社区贡献的负担，并有效跟踪这些贡献。
--> 项目评估（11 月 30 日 - 12 月 5 日） 提交项目报告和对我的导师的评估 撰写并提交我参加 Google 文档赛季的体验报告。
为什么是此项目？ 我相信，要想进一步采用并更好地使用代码，就必须用精心编写且版本化的文档来补充代码。就个人而言，我非常喜欢 CERN 在不同物理学领域开创前沿研究的方式。鉴于此类实验过程中处理、传输和生成的信息规模庞大，我一直很好奇如何在组织内管理数据，以供参考和未来使用。非常荣幸能够为改进相关框架的贡献做出贡献，而该框架为一些令人惊叹的科学研究和发现提供有力支持。
为什么我是此项目的合适人选？除了满足前提条件之外，我相信自己是此项目的合适人选，因为：
我已经着手修改 Kubernetes 的现有文档。这些贡献促使我成为 1.19 Kubernetes 版本周期的发布文档影子，在该阶段，我致力于有效地维护和升级发布期间新增功能的文档。 我相信，优秀的文档是优秀的产品/服务的基石。无论是程序性信息还是技术性信息，精心编写、简洁且易于获取的信息都会有助于推动应用采用并促进更好的使用。 在我的整个职业生涯中，我使用过数据驱动的分布式系统，相信我最容易理解与此类系统相关的文档要求的复杂性。作为最终用户，我熟悉文档写得不好/不正确的陷阱，并在结构调整时认真考虑这些因素。