GenPipes プロジェクト

このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。

プロジェクトの概要

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

プロジェクトの説明

「ドキュメントを読む」の GenPipes ドキュメントを設定するという目的を達成するために、3 ステップの計画を提案します。

ステップ 1: 概念実証

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

    • 情報の不足や不正確さを特定する
    • 新しいドキュメントのトピックを提案する（必要な場合）
    • 新規ユーザーに焦点を当ててターゲット オーディエンスに働きかけるための情報アーキテクチャ マップの下書きを作成する

    （注: このステップでは、RTD 用の Genpipes のドキュメントをホストできる新しい GitHub リポジトリのセットアップに関する、GenPipes メンターからの入力が必要になる場合もあります。この GitHub リポジトリを使用して、RTD ビルド パイプラインのすべてのドキュメントをインポートできます。これらを遵守する必要がある場合は、GenPipes リポジトリ ルールとドキュメント ソース管理ガイドラインに関する分析情報が必要になる場合があります。それ以外では、afaik という標準の形式を使用できます。また、概念実証には、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 の神々も見たいと思っていました。今のところは基本的な骨格ですが、時間が許せば 7 月 30 日まで更新する予定です。

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

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

  • GSoD のタイムラインを念頭に置いて、RTD でホストするために Sphinx/初期ベースのドキュメントにインポート、リンク、または変換できる現在または既存の GenPipes ドキュメントを特定します。

  • 特定したドキュメントを最初の形式に変換し、必要に応じて新しいドキュメントを作成し、可能なものや関連するものを再利用する

    • この初期ドキュメントを概念実証として ReadTheDocs にインポートし、保護されたリポジトリとしてホストします。レビュー/正式な切り替えが行われるまで、新規ユーザーに GenPipes の元のドキュメントを使用するよう促すメモを最初に記載する。

  • 復習/コース修正/更新

ステップ 3: 最初のドラフトを RTD で絞り込み、レビューして公開する

  • GenPipes の新しいドキュメント構造案の詳細を GenPipes TOC に記入 – 最初のいくつかのドキュメント（GenPipes Readme）以外のドキュメントを追加します。

  • 新しいユーザー、経験豊富な GenPipes ユーザー、GenPipes デベロッパーなどに対処するため、TOC に明確な境界を追加します。

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

レポート

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

その他のアイデア

今後（3 か月以降）もしあれば、私が GenPipes のプログラムを長期間維持できるようサポートできます。あるいは、必要に応じて他のメンバーもトレーニングします。この最初の 3 か月の結果に基づいて判断いたします。

また、プロジェクト提案の別のアイデアとして、オンボーディングを容易にする GenPipes 3 ページの概要を作成することをおすすめします。現在、新規ユーザーが GenPipes を使い始めるには、面倒な作業をこなさなければなりません。ドキュメントは良いものだが、ばらばらになっていて、新規ユーザーにとって有益ではないためです。3 か月以内に実現できるかどうかわかりませんが、試してみたいです。

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