moja グローバル プロジェクト

このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。

プロジェクトの概要

オープンソース組織:
moja global
テクニカル ライター:
Tlazypanda
プロジェクト名:
FLINT の技術オンボーディング ガイドのドキュメント
プロジェクトの長さ:
標準期間（3 か月）

プロジェクトの説明

新しいコントリビューターがメンテナンス担当者から最小限のサポートで簡単に利用を開始できるように、FLINT 向け技術オンボーディング ガイドのドキュメント。技術的なオンボーディングを通じて新しいコントリビューターをサポートします。

プロジェクトに関する問題

現在のドキュメントに関連する最も重要な問題のリストは次のとおりです。 - ローカル設定ガイドの手順が整理されていないため、新しいコントリビューターが開始しにくい。- FLINT の複数のリポジトリには目的のドキュメントがなく、相互にリンクされていないため、新規ユーザーがどのリポジトリをインストールする必要があるかを特定することが困難です。- Windows のインストールは十分にドキュメント化されていますが、Linux ベースのインストールのドキュメントには改善の余地があります。- Git ワークフローは現在ドキュメントの一部ではありません

おすすめするソリューション

この提案では、新しいコントリビューターが技術的なオンボーディングをスムーズに完了し、メンテナーからの最小限のサポートで簡単に作業を開始できるようにするソリューションを提示します。これは、現在のドキュメントをリファクタリングして初心者向けにわかりやすくし、利用可能なすべてのドキュメントを中央のスタンドアロン リポジトリで管理することで実現できます。このプロジェクトは次の 3 つのフェーズに分かれています。- - 既存のドキュメントのレビューとリファクタリング: このフェーズの目標は、現在のガイドを見直し、新しいコントリビューターが簡潔かつ簡単に理解できるようにリファクタリングすることです。また、初心者向けにドキュメントを変更し、バッジ、絵文字、first-timers-only タグまたは good first issue タグが付けられた問題に関する情報を追加する必要があります。- 中央のスタンドアロン ドキュメント リポジトリを作成する: このフェーズの目標は、スタンドアロン リポジトリで利用可能なすべてのドキュメントを論理的な順序でリンクすることです。これには、寄付に関するガイドライン、プロジェクトの設定手順、手順ガイドの順序付けが含まれます。 - 新しいデベロッパー向けのデベロッパー ワークフローとコミュニティ ウェブサイトを追加する: このフェーズでは、テストと QA のガイドラインとともに、Git への貢献に関するガイドラインとプロジェクトの技術アーキテクチャを含むデベロッパー ワークフローを追加します。提案されるコミュニティ ウェブサイトは、ワークフロー、新規コントリビューターが申請できる初回問題、すべてのコントリビューターのリストを表示する単一ページ アプリケーションです。 フェーズ 1: 既存のドキュメントとリファクタリングを確認する

次のリポジトリの現在のドキュメントを変更します。 - FLINT: 現在のドキュメントは詳細ではなく、必要な前提条件ライブラリの順序が示されていません。手順ガイドは複数の PDF に分割されていますが、1 か所にまとめることで、より簡潔にすることができます。また、インストール ガイドは Windows に対応していますが、Linux インストールでは FLINT.docker リポジトリにリダイレクトする方が役立つ場合があります。- FLINT.docker: 現在のドキュメントには、このリポジトリを設定する目的（Docker を介して FLINT の Linux インストールを提供すること）が記載されていません。Docker によるサポートは Ubuntu 18.04（Bionic Beaver）に限定されていますが、他の Linux ベースのディストリビューションに拡張できます。現在のドキュメントでは、Dockerfile の順序的な設定方法と、makefile からビルドする方法に関する十分な情報も強調する必要があります。- FLINT.example: 現在のドキュメントには、このリポジトリを設定する目的（FLINT の使用例を提供する）が記載されていません。さまざまなサンプル実行は、実行する特定の手順で区別できます。また、このリポジトリをメインの FLINT リポジトリにリンクして、ユーザーがこのページに移動してサンプルを実際に確認できるようにする必要があります。

現在のドキュメントに次の情報を追加する必要があります。 - Git と GitHub の使用: リポジトリのフォーク、クローン作成、リモート アップストリームの設定方法に関する手順が含まれます。また、最新のマスターに対してリベースし、マージの競合を処理する方法についても説明します。- バッジと絵文字: 現在のドキュメントには、新しいコントリビューターが歓迎されていると感じ、問題を簡単に見つけられるようにするバッジと絵文字がありません。 - 初心者向けの問題に関する情報: 新規コントリビューターを初心者向けの問題とコミュニティ ウェブサイトに誘導するのに役立ちます。- Import-me リポジトリに関する情報: Import-me リポジトリは、Moja Global リポジトリを迅速に開始するためのベースライン テンプレートとして機能します。現在のドキュメントでは、その重要性について言及されていません。Import-me リポジトリについて言及するように更新し、新しいリポジトリを作成するときにテンプレートとしてこれを選択する手順も追加する必要があります。また、Import-me リポジトリの追加機能を提案するためのプロセスも確立する必要があります。

フェーズ 2: 一元化されたスタンドアロンのドキュメント リポジトリを作成する

ホスティング プラットフォームに使用するツール:

このホスティング プラットフォームに推奨されるツールは、Read The Docs です。理由は次のとおりです。- さまざまなホスティング プラットフォームの中で高い評価を得ています。- commit のプッシュ時の自動更新 - 大規模なコミュニティであるため、設定やトラブルシューティングのサポートが容易 - ドキュメントは reStructuredText でフォーマットされ、出力は Sphinx によってコンパイルされます。

すべてのコンテンツを論理的な順序で整理します。

提案するコンテンツの順序は次のとおりです。- - デベロッパー向けドキュメントの概要: このセクションでは、Moja Global と FLINT の概要について説明します。 - 貢献: このセクションは、「コントリビューションの方法」（コード/バグの報告/翻訳/ドキュメント/イベントの編成など）と「行動規範」のサブセクションで構成されます。 - 開発のセットアップ: このセクションは、「Git と GitHub のワークフロー」、「Windows のインストール」、「Linux のインストール」のサブセクションで構成されます。 - デベロッパー ワークフロー: このセクションでは、次のテスト フェーズと、統合ツールの pull フェーズについて説明します。- 参加する: このセクションでは、Slack チャンネルなどのさまざまなソーシャル フォーラムを提供し、Moja Global とつながり、協力する。

フェーズ 3: 新しいコントリビューター向けのデベロッパー ワークフローとコミュニティ ウェブサイトを追加します。

デベロッパー ワークフローのドキュメント:

デベロッパー ワークフローのドキュメントは、次のサブセクションで構成されます。

  • 使用されているテクノロジー スタック/アーキテクチャとコード内のさまざまなモジュール: 実装されているテクノロジー スタック、コードベースのさまざまなライブラリとモジュールを新しいコントリビューターに紹介するドキュメント。
  • 統合されたテストツールとカバレッジ ツール: テストに使用される CI/CD パイプライン ツール、コードに対して実行されるカバレッジ ボット、自動品質チェックに新しいコントリビューターを導入します。また、テストが失敗した場合に連絡すべき担当者に関するガイドラインも提供します。
  • ワークフローを簡素化するために使用される bot（例: Zulipbot）。bot に表示するコンテンツ テンプレートの設計や、ユーザーが bot を理解し、貢献することで bot の構成を改善できるようにするドキュメントの提供。
  • プルリクエストの手動テストと送信: 特定の標準に対してプルリクエストを手動でテストし、プルリクエストの送信時にスクリーンショットまたは GIF として結果をアップロードする方法に関するドキュメント。
  • コントリビューターが遵守するプルリクエストの審査ガイドライン: 特定のチームに審査のタグを付け、プルリクエストに「審査が必要」などのラベルを追加して、メンテナーが返信できるようにするガイドライン。
コミュニティ ウェブサイト:

コミュニティ ウェブサイトには次の機能があります。

  • ワークフローに関する情報: ワークフローは、新規コントリビューターが最初に行う一連のアクションで構成されます。たとえば、初心者向けの問題を報告し、他のユーザーのために初心者向けの問題を作成し、フィードバックを提供する、プルリクエストを確認するなどです。
  • 初回のみの問題のリスト: 初回参加者または新しいコントリビューター向けの問題のリスト。
  • 最新でない問題のリスト: 長期間対応されていないため、コントリビューターが選択可能な問題のリスト。
  • コントリビューターのリスト: これまでに Moja Global リポジトリに貢献したコントリビューターのリスト。
  • 最近のコントリビューター: Moja Global リポジトリに最近貢献したコントリビューターのリスト。
  • チャット フォーラムに参加するためのリンク: Slack コミュニティに参加してクエリを解決したり、プロジェクトについてさらにディスカッションしたりするための情報とリンク。