GenPipes プロジェクト

このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。

プロジェクトの概要

オープンソース組織:
GenPipes
テクニカル ライター:
shaloo
プロジェクト名:
Read The Docs で GenPipes のドキュメントを設定する
プロジェクト期間:
標準の期間（3 か月）

プロジェクトの説明

「Read The Docs」に GenPipes のドキュメントを設定するという目標を達成するための 3 段階の計画を提案します。

ステップ 1: PoC

  • 新規ユーザー / 研究者として GenPipes の既存のドキュメントを確認する

    • 不足している情報や不正確な情報を特定する
    • 新しいドキュメントのトピックを提案する（必要に応じて）
    • 新規ユーザーを中心に、ターゲット オーディエンスに対応する情報アーキテクチャ マップの下書き。

    （注: このステップでは、RTD の genpipes ドキュメントをホストできる新しい GitHub リポジトリの設定について、GenPipes メンターの入力が必要になる場合があります。この GitHub リポジトリを使用して、RTD ビルド パイプラインのすべてのドキュメントをインポートできます。これには、GenPipes リポジトリのルールとドキュメント ソース管理ガイドライン（遵守が必要な場合）に関する分析情報が必要になる場合があります。それ以外の場合は、標準のものを使えるようです。また、PoC では、GitHub アカウントを使用してサンプル RTD リポジトリ設定のデモを行うことができます（例: https://gpdocs.readthedocs.io/en/latest/）。これは、この提案用に作成したサンプラーです）。

  • 前のステップのレビューと分析に基づいて、提案する GenPipes ドキュメントの構造 / インデックスの最低限のスケルトンを作成し、RTD サイトに掲載します。

    • これには、GitHub リポジトリの作成（Sphinx ツールを使用）と基本的なドキュメント ファイルが含まれます。
    • これには、さまざまなセクション / フローについて新規ユーザーと経験豊富なユーザーの両方を念頭に置いた新しい TOC の作成も含まれます。

  • ベースラインの骨組み TOC を確認 / 承認を得る

    GenPipes GSoD の評価フェーズでは、RTD でホストされているこのサンプルを使用して、GenPipes の価値を創造しようとしました。これはデモ専用の保護されたリンクであり、RTD ではまだ公開されていません。候補リストに入るかどうかに関係なく、このデモは GenPipes RTD の取り組みを活性化するために使用できます。ソースは c3g/GenPipes GitHub リポジトリにすでにチェックインされています。メンターの Rola と Hector は、Skype の「画面共有」についての議論で気に入っていたので、GSoD Gods も見たいかもしれないと思いました。現時点では、最低限の骨組みですが、7 月 30 日までに時間がある場合は更新する予定です。

https://genpipes.readthedocs.io/en/latest/

ステップ 2: GenPipes Doc v0.9 ドキュメント セットの作成

  • GSoD のタイムラインを考慮しながら、RTD でホストするために、現在の GenPipes ドキュメントまたは既存の GenPipes ドキュメントをインポート、リンク、または Sphinx/rst ベースのドキュメントに変換できるドキュメントを特定します。

  • 特定したドキュメントを rst 形式に変換し、必要に応じて、該当する場合は新しいドキュメントを作成し、可能な限り関連するドキュメントを再利用します。

    • この初期ドキュメント セットを概念実証として ReadTheDocs にインポートし、保護されたリポジトリとしてホストする。レビュー/正式な切り替えが承認されるまで、新しいユーザーには GenPipes の元のドキュメントにアクセスすることを提案するメモを事前に記載します。

  • レビュー/コースの修正/更新

ステップ 3: RTD で最初の下書きを調整、確認、公開する

  • 提案された GenPipes の新しいドキュメント構造の詳細を GenPipes の TOC に入力します。最初のドキュメント（GenPipes Readme）、コンセプト、チュートリアルなどに加えて、別のドキュメントを追加します。

  • 新しいユーザー、経験豊富な GenPipes ユーザー、GenPipes デベロッパーなどに対応できるよう、TOC に明確な区切りを追加しました。

  • RTD（sphinx ビルド）を介した部分的な自動化を含む作業プロセスを提案し、ユーザーが GenPipes ドキュメントセットを維持、編集する方法と、C3G が外部ドキュメント作成者にそのことを許可するかどうかについて話し合います。これには、コーディング ガイドラインと同様に、ドキュメントを更新するためのガイドラインの作成が必要になる場合があります。追加のサブステップが必要になる場合があります。たとえば、GenPipes ドキュメントで、PR の承認前にスペルチェックを自動化します。

報告

最後に、経験、ログ、メンターからのフィードバックに基づいて GSoD のレポートを作成します。

その他の考え

今後（3 か月以上）、必要に応じて、GenPipes でこの状態を長期的に維持できるようにサポートします。必要に応じて、他のユーザーにトレーニングを実施します。この 3 か月間の結果に基づいて判断できます。

また、プロジェクト提案のアイデアとして、オンボーディングを容易にする GenPipes の 3 ページの概要を作成することをおすすめします。現在、ドキュメントは充実していますが、散在しており、新規ユーザーには使いづらいため、新規ユーザーが GenPipes を使い始めるまでには多くの手順を踏む必要があります。3 か月以内に完了できるかどうかはわかりませんが、試してみます。

この提案とその経緯（履歴）は、https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing でも確認できます。