このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。
プロジェクトの概要
- オープンソース組織:
- CERN-HSF
- テクニカル ライター:
- Ariadne
- プロジェクト名:
- Rucio - Rucio ドキュメントのモダナイゼーション（再構成と書き換え）
- プロジェクト期間:
- 標準期間（3 か月）
プロジェクトの説明
概要: Rucio フレームワークは、異種のデータセンターに地理的に分散された大量の科学データを管理および整理することを目的として開発されました。分散データ復元や適応型レプリケーションなどの機能を備え、スケーラビリティに優れ、モジュラーで拡張可能です。このようなサービスのドキュメントを使用するユーザーは、さまざまなバックグラウンドを持ち、アクセスする際の要件もさまざまです。そのため、このようなサービスのドキュメントは、エンドユーザーによる導入と利用を簡素化するとともに、一般的な問題とトラブルシューティングの参考となるようにする必要があります。
このようなドキュメントがないと、効率的で効果的な活用に大きな障害が生じます。これにより、サポート費用が増加し、プロダクトの企業イメージに悪影響が及ぶ可能性があります。ドキュメントは、結局のところコミュニケーションの手段です。したがって、コミュニケーションを成功に導くためには、適切なバージョニングの関連性を維持しながら、管理しやすくアクセスしやすいフレームワークにコミュニケーションをカプセル化する必要があります。
執筆時点では、Rucio フレームワークは、LHC での ATLAS と CMS の測定で高エネルギー要件を満たすために使用されています。また、天体物理学など、LHC 以外の多様な科学コミュニティのニーズをサポートするためにも使用されています。そのため、ドキュメントは可能な限り関連性があり、アクセスしやすいものにする必要があります。CERN は、このプロジェクトを通じて、関連するすべてのドキュメントにアクセスできる一元化されたビューを提供することで、Rucio のエンドユーザーがフレームワークを活用しながらシームレスなエクスペリエンスを実現できるようにしたいと考えています。
現在の状況: 現時点では、ユーザー ドキュメントはさまざまな場所に分散しており、科学論文、コード内のソースを含む readthedocs.io、Google ドライブ、GitHub、DockerHub、ウィキなど、複数の形式で提供されています。複数のソースを使用すると、バージョンの追跡やドキュメントの正確性に問題が生じます。また、ドキュメントの分散モデルでは、特定のユースケースに関連する情報をナビゲートして表示することが非常に困難です。特に 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
Wiki リンク: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
科学論文 リンク: https://arxiv.org/abs/1902.09857
これらのソースのドキュメントは形式が異なります。たとえば、Google ドライブにはスライドとドキュメントの形式のドキュメントがあり、GitHub には主に reStructuredText マークアップ言語のファイルが存在します。バージョニングやトラッキングが行われていないため、複数のソースに冗長な情報が公開されています。 情報のラベル付け/分類に均一性がない。そのため、検索には過去の経験と専門知識が必要です。
さまざまな形式とソースがあるため、mkdocs を使用して情報を再構成し、一元化することが期待されます。ツールについての理解を深めるために、ツールの使用方法について調査し、習熟しました。
判定: 既存のドキュメントは非構造化で、適切なリンクなしに分散しています。また、書式設定の集中化と均一性も欠けています。そのため、ユーザーは検索に余分な手間をかけなければなりません。また、このようなギャップは管理者、メンテナンス担当者、リードに不要なプレッシャーをもたらします。その結果、ドキュメントのメンテナンスと更新にコミュニティ主導のアプローチを維持することが難しくなります。ユーザーとコントリビューターのエクスペリエンスが大幅に低下し、
提案するドキュメントの構造: 要件を徹底的に分析した結果、ドキュメントのモデルを再構築して、主な問題に対処することにしました。
以下に添付したモックアップに、再構成されたモデルを示します。このモデルでは、すべてのドキュメントを以下の 7 つのカテゴリに分類します。
- 概要
- スタートガイド
- コンセプト
- Rucio インターフェース
- タスク
- チュートリアル
- 高度なノウハウ
もちろん、リンクの追加など、このプログラムの終了後に取り組みたい改善もあります。Rucio の 500 ペタバイトのデータにアクセスするアクティブ ユーザーが 1, 000 人を超えているため、ドキュメントの再構成により、ユーザーがサポートのメーリング リストに頼る必要性が大幅に軽減されるはずです。ターゲットは、クリック率を低減し、分類とラベル付けによってドキュメントを簡単に表示することで、ユーザー エクスペリエンスを向上させることです。ユーザー、運用、管理担当者が知る必要があるすべての情報が、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 で分類されたドキュメントが分析され、重複や冗長な情報源がないか確認されます。プロジェクト情報に記載されているとおり、Google は利用可能なすべての情報について、信頼できる単一の情報源を目指しています。
--> マイルストーン 3: 一元化と再フォーマット: ETC: 2020 年 11 月 9 日 ドキュメントを適切に削除して再構成したら、まず再フォーマットを目指します。ソースが異なるため、形式が異なり、まず適切な形式に変換する必要があります。これが完了すると、一元化プロセスが容易になります。
--> マイルストーン 4: トラッキング ボードの設定 + ガバナンス/コントリビューションに関するドキュメントなど: 2020 年 11 月 23 日このフェーズは、プロジェクトの完了後もドキュメントが引き続き更新されるようにするためのものです。ガイドラインを定め、プロジェクト ボードを設定すると、コミュニティからの貢献を募集し、効果的に追跡する管理メンバーの負担を軽減できます。
--> プロジェクト評価（11 月 30 日～ 12 月 5 日） プロジェクト レポートとメンターの評価を提出 Season of Docs 参加者としての経験に関するレポートを作成して提出します。
このプロジェクトの目的 コードを、よく記述されたバージョン管理されたドキュメントで補完することが、さらなる導入とより良い使用を可能にする唯一の方法であると信じています。個人的には、CERN が物理学のさまざまな分野で最先端の研究を先導してきたことに興味をそそられています。このようなテストで処理、転送、生成される情報の規模を考えると、組織内での参照と将来の使用のためにデータがどのように管理されているのか、いつも興味を持っていました。素晴らしい科学研究や発見を支えてきたフレームワークのドキュメントの改善に貢献できることを光栄に思います。
なぜ私がこのプロジェクトに適任なのか？ 前提条件を満たしているだけでなく、以下の理由から、このプロジェクトに適した人物であると確信しています。
すでに Kubernetes の既存のドキュメントの変更に取り組んでいます。こうした貢献により、1.19 Kubernetes リリース サイクルのリリース ドキュメント シャドウとして登録され、リリース時に追加される新機能のドキュメントを効果的に維持、アップグレードする役割を担っています。優れたドキュメントは優れたプロダクト/サービスの基盤となると考えています。手順や技術的な情報であっても、わかりやすく簡潔で、簡単にアクセスできる情報は、導入を促進し、より効果的な使用に役立ちます。キャリアを通じてデータドリブンの分散システムを扱ってきた私は、そうしたシステムの文書化に関する要件の複雑さを理解するのに最適な立場にあると考えています。私自身もエンドユーザーでしたが、ドキュメントの記述が悪く、ドキュメントが不正確な場合の危険性を熟知しており、再構成の際にそれらの点も考慮に入れる必要があります。