このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- CERN-HSF
- テクニカル ライター:
- アリアドネ
- プロジェクト名:
- Rucio – Rucio ドキュメントのモダナイズ（再構築と書き換え）
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
要約: Rucio フレームワークは、異種データセンター間で地理的に分散した大量の科学データを管理、整理する目的で開発されました。分散データ復旧や適応型レプリケーションなどの機能を提供するこのフレームワークは、スケーラビリティに優れ、モジュール式かつ拡張可能です。このようなサービスのドキュメント利用者の背景はさまざまで、アクセスする際の要件もさまざまです。そのため、このようなサービスの優れたドキュメントは、エンドユーザーにとっての導入と利用を簡素化すると同時に、一般的な問題やトラブルシューティングの参照にもなる必要があります。
そのようなドキュメントがなければ、効率的かつ効果的な利用において大きなハードルがあるでしょう。これにより、サポート費用が増加し、プロダクトの企業アイデンティティに対する風評リスクにつながる可能性があります。結局のところ、ドキュメントはコミュニケーションの手段です。したがって、コミュニケーションを、管理しやすくアクセスしやすいフレームワークにカプセル化し、適切なバージョニングと関連性を維持することは、成功のためのコミュニケーションを行うことです。
本稿の執筆時点で、LHC での ATLAS と CMS の実験における高エネルギー要件の実現には、Rucio フレームワークが利用されています。また、LHC だけでなく、天体物理学などの多様な科学コミュニティのニーズにも対応するためにも使用されています。そのため、可能な限り関連性が高く、利用しやすいドキュメントを作成することが必要になります。CERN はこのプロジェクトの支援を受け、すべての関連ドキュメントにアクセスするための一元的なビューを提供することで、Rucio のエンドユーザーがフレームワークを活用しながらシームレスなエクスペリエンスを提供できるようにしたいと考えています。
現状: 現在、ユーザー ドキュメントはさまざまな場所に散在しており、科学記事、コード内にソースがある readthedocs.io、Google ドライブ、GitHub、DockerHub、Wikis など複数の形式があります。複数のソースが存在すると、バージョンの追跡やドキュメントの正確性に問題が生じます。さらに、ドキュメントの分散モデルでは、特定のユースケースに関連する情報のナビゲーションと表示に大きなハードルがあります。特に Wiki の場合、特定のテストで提供された情報は、同じソースまたは他のソースに存在する他のインスタンスにも非常に応用できる可能性があります。しかし、こうした情報は統合と適切な連携が欠如しているため、休眠状態にあり、十分に活用されていない可能性があります。
提案したユーザー ドキュメントが現在のドキュメントよりも改善されているのはなぜですか。以下に提案するモデルは、多面的な問題を考慮して、以下で詳述するように、ドキュメントのナビゲーション、バージョニング、トラッキング、表示といった障害を取り除きます。
ドキュメントの再構成は、エンドユーザーが操作を行う際に費やした労力を簡略化することを目的としています。情報を検索するときにうさぎの穴に潜む必要はありません。分類やラベルが付けられるので、わかりやすくなります。管理の観点からは、再構築によって要件に基づいて自由にカテゴリ分けが可能になるため、バージョニングとトラッキングが容易になります。 再構築されたドキュメントをすべて一元化すると、複数の情報源を参照しなくても、すべての情報がユーザーに表示されるようになります。
分析: 要件の概要を読み、メンタリング チームと話し合った結果、Rucio ドキュメントの現状について次のように推測しました。
ドキュメントの主な提供元は 6 つあります。 - Google ドライブのリンク: https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Sphinx 搭載の Readthedocs（コードのソースを含む） コードへのリンク: 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 ドライブにはスライドやドキュメントの形式のドキュメントがありますが、GitHub には主に reStructuredText マークアップ言語のファイルがありますが、バージョニングとトラッキングが不足しているため、複数のソースに冗長な情報が公開されています。情報のラベル付け/分類に均一性がない。そのため、検索を行う際は過去の経験と専門知識が求められます。
形式とソースが無数にあることを考えると、情報を再構築し、mkdocs を使用して一元化することが期待されます。各ツールについて理解を深めるため、その使用方法について調査し、よく理解しました。
判定: 既存のドキュメントが構造化されておらず、適切なリンクがない状態で散らばっている。また、一元化されておらず、形式が統一されていないという問題もあります。その結果、ユーザーは検索に余分な労力を費やさなければなりません。また、このようなギャップにより、管理者/管理者/リードに不必要なプレッシャーが生じ、ドキュメントのメンテナンスや更新に関してコミュニティ主導のアプローチを維持することが困難になります。ユーザーと投稿者のエクスペリエンスは著しく低下し、繰り返し発生することになる
提案するドキュメントの構造:
要件を徹底的に分析した後、ドキュメントの再構築モデルによって主な課題に対処することにしました。
再構成モデルは、添付のモックアップで紹介されています。各ドキュメントは以下の 7 つのカテゴリに分類されます。
- 概要
- はじめに
- 概念
- Rucio インターフェース
- タスク
- チュートリアル
- 高度なノウハウ
もちろん、改善はあります。たとえば、このプログラムの終了後に手がけたいリンクを追加するような改善です。1, 000 人以上のアクティブ ユーザーが Rucio の 500 ペタバイトのデータにアクセスしているため、ドキュメントの再構築を提案することで、ユーザーがサポート メーリング リストに頼る必要性を大幅に低減できるはずです。目標は、クリック率を下げ、分類とラベル付けによってドキュメントを簡単に表示することで、ユーザー エクスペリエンスを向上させることです。ユーザー、オペレーション、管理者の観点から必要な情報を 3 回以内に入手できます。
モックアップ リンク: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing）
プロジェクトの目標: - さまざまな情報源から入手可能な冗長な情報を分析し、取り除きます。つまり、すべての情報に信頼できる情報源を 1 つ設定します。 - 既存のドキュメントのラベルとカテゴリ分けによる再構成 - 再構築されたドキュメントを 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 日） プロジェクト レポートとメンターの評価を提出する ドキュメント シーズンに参加した体験を報告し、提出する。
このプロジェクトの目的 私は、適切に記述され、バージョニングされたドキュメントでコードを補完することが、さらなる採用と利用の向上を実現する唯一の方法だと確信しています。個人的には、CERN が物理学のさまざまな分野で最先端の研究を先導してくれていることに、非常に魅了されました。このような実験中に処理、転送、生成された情報の規模が大きくなることから、参照や今後の組織内での使用のためにデータがどのように管理されているかにいつも興味がありました。卓越した科学研究と発見の原動力となったフレームワークについて、ドキュメントの改善に貢献できれば幸いです。
私がこのプロジェクトの適任者である理由私は、前提条件を満たすことに加えて、以下の理由でこのプロジェクトの適切な担当者になると確信しています。
すでに Kubernetes の既存のドキュメントの修正に取り組んでいます。その結果として、私は 1.19 Kubernetes リリース サイクルのリリース ドキュメント シャドーイングに選ばれ、リリース中に追加される新機能のドキュメントの効果的な保守とアップグレードに貢献しています。 優れたドキュメントは、優れたプロダクト/サービスの根幹であると考えています。手続き型であれ、技術的なものであれ、適切に記述され、簡潔で、アクセスしやすい情報は、採用を促進し、より良い使用を促進するための原動力となります。キャリア全体を通してデータドリブンな分散システムに取り組んできた私は、そのようなシステムのドキュメントに関する要件の複雑さを理解するのに最適だと考えています。私自身もエンドユーザーですので、文章が不適切または不正確であることはよく理解しており、再構成の際にはその点を考慮するように注意しています。