本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- CERN-HSF
- 技术文档工程师：
- Ariadne
- 项目名称：
- Rucio - 对 Rucio 文档进行现代化改造（重构和重写）
- 项目时长：
- 标准时长（3 个月）
Project description
摘要： 我们开发 Rucio 框架是为了管理和组织分布在不同地理位置的异构数据中心中的大量科学数据。该框架提供分布式数据恢复和自适应复制等功能，具有高度可扩缩性、模块化和可扩展性。此类服务的文档使用者来自不同的背景，在访问文档时有不同的要求。因此，此类服务的文档应完善，以便最终用户更轻松地采用和使用该服务，同时也能作为常见问题和问题排查的参考。
如果没有此类文档，则会在高效利用方面遇到重大障碍。这可能会导致支持成本增加，并为产品的企业身份带来声誉风险。毕竟，文档是一种沟通方式。因此，确保将通信封装在可管理且易于访问的框架中，同时保持与适当的版本相关，有助于我们确保通信取得成功。
在撰写本文时，Rucio 框架已被用于为 LHC 中 ATLAS 和 CMS 实验的高能耗需求提供支持。它还用于满足除了大型强子对撞机之外的多元科学界（例如天体物理学）的需求；因此，文档必须尽可能相关且易于访问。借助此项目，CERN 希望通过提供集中视图来访问所有相关文档，让 Rucio 的最终用户在使用该框架时获得无缝体验。
现状： 截至目前，用户文档分布在不同地方，并采用多种格式，包括科学文章、包含源代码的 readthedocs.io、Google 云端硬盘、GitHub、DockerHub 或 Wikis。多个来源会导致文档版本跟踪和正确性方面的问题。此外，分散式文档模式在导航和显示特定用例的相关信息方面存在重大障碍。特别是在维基百科的情况下，为特定实验提供的信息很可能也适用于位于同一/其他来源中的其他实例。但是，由于缺乏整合和适当的联系，这些信息处于休眠状态，并且可能未得到充分利用。
为什么您提议的用户文档比当前文档更完善？ 鉴于这一多面性问题，下文提出的模型消除了文档导航、版本控制、跟踪和呈现方面的障碍，具体如下：
调整文档的结构是为了简化为最终用户导航所耗费的工作量。用户在搜索信息时无需深入探究，因为信息会被分类/标记以简化搜索过程。从管理角度来看，版本控制和跟踪会变得更加容易，因为重构可让您根据需求自由地进行分类。集中管理所有重构的文档，可确保用户无需查看多个来源，即可查看所有信息。
分析：阅读需求简介并与指导团队沟通后，我对 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
Wiki 链接：https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
科学文章 链接：https://arxiv.org/abs/1902.09857
这些来源的文档采用不同的格式。例如，Google 云端硬盘中的文档以幻灯片和文档的形式提供，GitHub 中的文件主要采用 reStructuredText 标记语言等。由于缺少版本控制和跟踪功能，导致在多个来源中发布了冗余信息。信息的标签/分类不一致。因此，搜索时需要过往经验和专业知识。
鉴于信息的格式和来源众多，预计需要使用 mkdocs 重构信息并将其集中管理。为了更好地了解这些工具，我进行了研究并熟悉了它们的用法。
判定结果：现有文档结构不清、散乱无序，且缺少适当的链接。而且，格式设置也缺乏集中化和统一性。这会导致用户在搜索时需要付出额外的努力。这种差距还会给管理员/维护者/主管带来不必要的压力，因此很难采用社区驱动的方法来维护和更新文档。用户和贡献者的体验会大幅下降，并且会重复
建议的文档结构：
在对要求进行全面分析后，我决定通过重构文档模型来解决主要问题。
下方附上了重构后的模型的模拟图，该模型会将每一份文档归入以下 7 个类别：
- 简介
- 使用入门
- 概念
- Rucio 接口
- Tasks
- 教程
- 高级专业知识
当然，还有一些改进措施，例如在完成此计划后添加链接。超过 1, 000 名活跃用户在 Rucio 上访问 500 个 petabyte 的数据，我们建议对其文档进行重组，这样应该可以大大减少用户求助于支持邮寄名单的需要。其目标是降低点击率，并通过分类和标签轻松显示文档，从而改善用户体验。用户/运营/管理人员需要了解的所有信息都应在 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 中分类的文档，看看是否存在重复和冗余的信息来源。正如项目信息中所述，我们希望所有可用信息都来自一个可信来源。
--> 里程碑 3：集中管理和重新格式化： ETC：2020 年 11 月 9 日 在文档经过适当的修剪和重构后，我会先着手重新格式化。由于来源不同，格式也不同，因此需要先转换为适当的格式。完成后，集中化流程会变得更简单。
--> 里程碑 4：设置跟踪板块 + 治理/贡献等文档：2020 年 11 月 23 日 此阶段旨在确保项目完成后，文档会持续更新。制定准则并设置项目板会减轻管理员的负担，让他们能够有效地征求社区贡献并进行跟踪。
--> 项目评估（11 月 30 日 - 12 月 5 日） 提交项目报告和对我的导师的评估 撰写并提交我参与 Google 文档季的体验报告。
为什么要选择此项目？ 我相信，只有使用精心编写的、有版本控制的文档来补充代码，才是进一步采用和更好地使用的唯一方法。我个人非常赞赏欧洲核子研究中心在物理学不同领域开拓前沿研究的方式。考虑到此类实验处理、传输和生成的信息规模，我一直很想知道如何管理数据，以供组织内部参考和日后使用。能为这个框架改进文档，我深感荣幸。这个框架为一些令人惊叹的科学研究和发现提供了强大的支持。
为什么我适合参与此项目？ 除了符合前提条件外，我还非常有信心胜任此项目，因为：
我已经在修改 Kubernetes 的现有文档。正是这些贡献，让我成为了 1.19 Kubernetes 版本周期的版本文档 Shadow，负责为发布期间添加的新功能有效维护和升级文档。 我认为，优质文档是打造优质产品/服务的基础。无论是程序还是技术方面，精心编写、简洁且易于访问的信息都将推动产品采用并帮助更好地使用。 在我的整个职业生涯中，我一直在使用数据驱动的分布式系统，因此我认为自己最有能力了解此类系统文档方面的复杂要求。我本人就是最终用户，因此非常熟悉编写不当/不正确文档的陷阱，在重构过程中会谨慎考虑这些问题。