Linux Foundation プロジェクト

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

プロジェクトの概要

オープンソース組織:
The Linux Foundation
テクニカル ライター:
jaskiratsingh2000
プロジェクト名:
CHAOSS: CHAOSS コミュニティ全体向けハンドブックを作成する
プロジェクトの長さ:
標準期間（3 か月）

プロジェクトの説明

プロジェクトの概要:

現在、CHAOSS コミュニティ内のワーキング グループは独自の作業方法を開発し、さまざまな程度で異なるプロセスを文書化しています。ワーキング グループには、共通指標 WG、ダイバーシティとインクルージョン WG、進化、リスク、価値のワーキング グループがあり、それぞれ独自の参加方法と働き方を設定し、さまざまなコミュニケーション方法と職場文化を適応させています。指標に応じて、これらのワーキング グループは、適切な指標に沿って、それぞれのワーキング グループ カテゴリでさまざまな研究開発をリードし、それぞれのカテゴリでさまざまな研究開発をリードするための適切なパスウェイを知っている、異なる重点分野とバックグラウンドを持っています。しかし、新規参加者と既存のコントリビューターは、それぞれの作業に参加する方法や、適切なパスウェイを踏む方法を知らない場合があります。

その結果、CHAOSS コミュニティ内のものは標準化されていません。そのため、コミュニティ全体で適切なプロセスと職場の文化の基本を把握できるように、コミュニティ ハンドブックの目的は、重要な情報を一元化し、CHAOSS プロジェクト全体でその一部を標準化することになっています。重要な情報と標準化のパートでは主に、CHAOSS が使用するプロセスに重点を置きます。これは、CHAOSS がコミュニティの成果をどのように達成するかについて合意を得るか、新しいメンバーがコミュニティに参加し、コミュニティの基本に従う方法、新規または既存のメンバーが CHAOSS コミュニティ内のリーダーシップを利用するために従うべきプロセスと道筋です。

ハンドブックは、CHAOSS プロジェクトで作業を行う方法について、既存および新規のコミュニティ メンバー向けの説明書として機能する必要があります。このプロジェクトには、ハンドブックのコンテンツを収集して整理するクリエイティブな要素と、ハンドブックの表現方法を定義する技術的な要素が含まれます。

なぜ必要なのですか？

コミュニティ ハンドブックは、コミュニティの主要なポリシーと手順を定義し、コミュニティの使命、価値観、機能の概要を説明するドキュメントです。

このハンドブックでは、コミュニティに新しく参加したメンバーに、コミュニティの概要と仕組みをわかりやすく説明しています。現在、CHAOSS コミュニティ ハンドブックは GitHub リポジトリで入手できますが、新規ユーザーと既存のコミュニティ ユーザー向けに情報を追加して刷新し、リファクタリングする必要があります。この CHAOSS コミュニティ全体向けハンドブックは、新規メンバーと既存のコミュニティ メンバーを次のようにサポートします。

  • CHAOSS コミュニティのポリシーを正式に整理し、1 か所にまとめる
  • コミュニティの概要、ミッション、ビジョン、リーダーシップを伝える
  • CHAOSS コミュニティの活動について
  • 投稿に関するガイドライン
  • プロジェクト ワークフローの定義
  • CHAOSS コミュニティの文化の概要
  • 全般的なよくある質問
  • メンターシップ

プロジェクトの説明:

コミュニティ ハンドブックはさまざまな「セクション」に分かれており、各セクションには、特定のトピックに関する適切で詳細な情報が含まれています。セクションは次の方法で分割できます。

  • はじめに
  • CHAOSS コミュニティとは
  • リーダーシップへの道
  • 用語
  • 投稿に関するガイドライン
    • デベロッパー
    • デザイナー
    • 編集者
    • マーケティング担当者
  • 指標
  • CHAOSScon
  • CHAOSScast
  • 会議の動画
  • 一般的なよくある質問
  • メンターシップ
    • Google Summer of Code
    • Outreachy
    • Google ドキュメント シーズン

詳細なプロジェクト成果物

1）概要:

このセクションは、CHAOSS コミュニティ ハンドブックの最初のページとして機能し、ハンドブックの詳細、概要、使用方法を取り上げます。以下に、その内容を記載します。

A.) そこにはウェルカム メッセージと CHAOSS コミュニティの簡単な説明が含まれており、ハンドブックを読者に理解してもらうのに役立ちます。また、コミュニティ内のさまざまな動きに焦点を当てた、こちら（https://chaoss.community/chaoss-photo-Album/）から撮影された画像のコラージュも掲載いたします。 B.) このページには、すべてのセクションの詳細も記載されており、各セクションの説明と適切なリンクが 1 行で示されます。 C.) ハンドブックの使用: ハンドブックの使用法はすでにここにあります（ shorturl.at/cqQU6 ）が、既存のハンドブックの使用を改良してリファクタリングし、ハンドブックのフローを含むマークダウンを改善します（ハンドブックに関連するものを追加、削除、議論する場合にどうなるかについても記載します。ハンドブック関連のコミュニケーション方法のプロセスに沿って対応します。ハンドブックのガイドライン（コミュニティと範囲内での使用を含む）、ハンドブックへの貢献（変更を行うためのリポジトリの使い方、PR の実施、ハンドブックとスタイルガイドに変更を加える場合に従うテンプレート）、ハンドブックに関するフィードバックの共有。[フィードバックの共有] には、テンプレートと、ユーザーがフォローアップしてフィードバックを提供する方法や、GitLab の問題を使用してフィードバックを受け取る方法を記載します。

2）CHAOSS コミュニティの方法:

CHAOSS のコミュニティへの参加は、コミュニティの慣習やガイドラインを理解してもらうために重要です。ワークフローにより、コミュニティのプラクティスをより強調し、最善の方法で概要を説明できます。このセクションには次のものが含まれます。

A.) 一般的な価値観: CHAOSS コミュニティ内での持続可能性、オープン性、透明性の取り扱い方法の概要。新規ユーザーや既存ユーザーがコミュニティ内で活動する際に、これらの価値観を理解し、考慮すべき点について説明します。B.) コミュニティ ガイドライン: CHAOSS コミュニティに参加する方法や基本的な利用規約の遵守方法など。また、コミュニティ内での働き方の文化についても説明します。（推奨事項と禁止事項）。コア コントリビューター/メンテナー向けのチェックリストが含まれ、メンテナーとの連携方法やチェックリストを他のユーザーに知らせることができます。C.) ワーキング グループ: このページ（https://chaoss.community/participate/）には、ワーキング グループの説明、リポジトリのリンク、ミーティングの情報など、ワーキング グループに関する情報が記載されていますが、ハンドブックには、各ワーキング グループに参加する方法、指標を評価するプロセス、各ワーキング グループの中心的なコントリビューターになる方法、理解する方法も記載します。

3）経営陣への道のり:

オープンソース プロジェクトでリーダーシップを獲得することは、商用の世界でコミュニティが成功するために不可欠な場合があります。そのため、以下を含めます。

A.) 技術的なリーダーシップ: リポジトリ管理者、ドキュメント作成者、ウェブサイト管理者のプロセスと責任が含まれます。 B.) ガバナンス リーダーシップ: 取締役と意思決定者のパスウェイが含まれます。 C.) オペレーション リーダーシップ: コミュニティ マネージャーのパスウェイが含まれます

4）用語:

用語は、CHAOSS コミュニティ内で頻繁に使用される用語とそれぞれの所属を説明するのに役立ちます。また、大文字表記、略語、使用を避けるべき単語などの用語の使用ガイドラインも、理由とともに記載します。対象となる規約は、CHAOSS Project、Open Source Community Health、Code Review、Working Group、Open Source Software Metric、Common Metric、Diversity、Inclusion Metric、Evolution Working Group、Risk Working Group、Value Working Group、Metric Release、Focus Area です。

5.）投稿に関するガイドライン:

ほとんどのオープンソース コミュニティは貢献やボランティア活動に依存しているため、これはオープンソース コミュニティの主なコンテキストです。これにより、コミュニティに参加する新規ユーザーやユーザーは、遵守すべき基本的な要件とガイドラインを理解できます。具体的には、以下の詳細が含まれます。

A.) コミュニティのロードマップの理解: このトピックでは、CHAOSS コミュニティのロードマップの概要について説明します。これにより、CHAOSS プロジェクト内のさまざまな作業に優先順位を付ける際に、どの方法やプロセスに従うべきかを把握できます。B.) 開発、ドキュメント作成、設計、テストなど、実践的な貢献を行うために必要なことを説明します。 C.) GitLab の仕組みの概要を説明する D.) 審査担当者/メンテナンス担当者ガイド

このセクションには、各貢献カテゴリの「役割と責任」も含まれます。以下に示します。

a）設計: このサブセクションには、「CHAOSS 設計ワークフロー」と設計ガイドラインが含まれます。設計ガイドラインには、設計分野に貢献する際にコントリビューターが遵守する必要がある設計原則、プロセス、使用ツールが記載されています。 b.) DEVELOPMENT: コードベースへの貢献に関するガイドが含まれます。技術的要件、プロジェクト構造、プロジェクトのセットアップ（Augur、Cregit、GremoireLab）が含まれます。 c.）ドキュメント: ツールやスタイルガイドなど、ドキュメントのリソースが含まれます。 d.) アウトリーチ: アウトリーチで CHAOSS コミュニティを支援する方法（ブログの作成、ソーシャル ハンドルの使用、オフ会やイベントの開催）など

6. 指標

現在、CHAOSS コミュニティ ウェブサイトには指標のリリースに関する情報が掲載されています（https://chaoss.community/metrics/）。このウェブサイトに指標ウェブサイトを掲載するための手順を理解することが重要です。このセクションでは、独自の指標をリリースするためのプロセスと作業について説明します。

7. CHAOSScon:

CHAOSScon に関する情報は GitHub（https://github.com/chaoss/governance/blob/master/community-handbook/chaosscon.md）とウェブサイト（https://chaoss.community/CHAOSScon-2020-NA/）にすでにありますが、CHAOSScon のプロセスと管理方法を説明する詳細と情報をハンドブックに追加することをおすすめします。ハンドブックには次の情報が記載されています。

A.) 組織委員会に関する詳細: CHAOSScon の組織委員会に参加する方法について説明します。 B.) 提案依頼プロセスの管理: 著者の登録、提案書とドキュメントの送信、審査、承認プロセスの管理など。C.) CHAOSScon プログラムの管理と公開 D.) 「広告、マーケティングの管理方法」 E）パッケージを含むスポンサーシップの提案と資金の処理方法

8.）CHAOSScast:

CHAOSScast の情報はこちら（https://github.com/chaoss/governance/blob/master/community-handbook/chaosscast.md）にあります。また、参加、組織委員会、広告、マーケティング資料などの追加情報とともにハンドブックに掲載されます。

9. 会議動画:

過去に YouTube で公開された会議の動画と、参加者、議題などの説明がすべて含まれます。

10.）一般的なよくある質問:

コミュニティ内でよく聞かれる一般的な質問が含まれており、新規メンバーや既存のコミュニティ メンバーがそれらの質問の一部に回答するのに役立ちます。

11.）Google Summer of Code:

このセクションでは、Google Summer of Code と参加条件、CHAOSS コミュニティで Google Summer of Code に参加する方法について説明します。このセクションには提案書のテンプレートも含まれており、ユーザーはこれを使用して提案書の下書き、役割、責任を負います。 また、既存のコミュニティ メンバーが組織管理者とメンターになるプロセスを学ぶのに役立つ情報も含まれます。

  1. Outreachy:

このセクションでは、Outreachy、参加条件、Outreachy の CHAOSS コミュニティに参加する方法について説明します。組織管理者とメンターになるプロセスなど、役割と責任についても説明します。

  1. Google Season of Docs:

このセクションでは、GSoD に関する情報、参加条件、GSoD の CHAOSS コミュニティに参加する方法について説明します。これには、組織管理者とメンターになるプロセスなど、ロールと責任が含まれます。

プロジェクトの想定される成果:

ハンドブックは、どのコミュニティでも重要な役割を果たします。同様に、この CHAOSS コミュニティ全体向けハンドブックにより、CHAOSS コミュニティ向けのより整理され、詳細なドキュメントが作成されます。コミュニティに参加する新規メンバーやコミュニティ内の既存のメンバーが、CHAOSS コミュニティの基本と仕組みを簡単に理解できるようになります。また、このハンドブックにより、CHAOSS コミュニティ内でさまざまなプロセスと、さまざまな職場文化へのパスが確立されます。

技術的詳細:

ハンドブックのメンテナンスには、Gitbook プラットフォームを使用することをおすすめします。これは、チームがより効果的かつ効率的に作業するためのユーザー フレンドリーなコラボレーション プロジェクトです。GitBook プラットフォームの一部の機能:

  • WYSIWYG: 高機能で見やすいテキスト エディタ
  • Markdown: マークダウンのショートカットを強力かつ効率的にサポート
  • リッチ埋め込み: 動画、コード スニペット、記事、音楽などの外部ウェブ コンテンツを埋め込みます。
  • ライター向けのダッシュボード: ビジュアル編集をサポートするインテリジェントなダッシュボードをライター向けに提供する
  • 下書き: 新しい変更の下書きを作成し、非同期で共同編集する
  • サポートのコメント: ドラフトの変更について話し合い、確認する
  • 文章作成履歴を追跡する: すべてを追跡します。変更を確認して元に戻す
  • 分析情報: トラフィック、評価、コンテンツの品質を追跡する分析情報もサポートされています
  • GitHub 同期: ワークフローを維持し、ドキュメントを GitHub と同期し続けます
  • カスタマイズのブランディング: カスタム ドメイン、カスタムロゴ、フォント、色、テーマ、ヘッダーなど

プラットフォームの概要を示す画像をいくつかご紹介します。

  • shorturl.at/GNQR4
  • shorturl.at/gATZ8
  • shorturl.at/qrE57
  • shorturl.at/rFRX6
  • shorturl.at/eyLW1
  • shorturl.at/rwHS8

-- ハンドブックはどこでホストされますか？

ハンドブックは GitBook 自体でホストされます。GitHub は、カスタム ドメイン、一般的なエラー、SEO に適したメカニズムを提供しています。

カスタム ドメイン: CHAOSS コミュニティがカスタム ドメインでホストする場合は、docs.chaoss.community のように表示されます。組織は、必要なサブドメインを構築する必要があります。組織のドメインを設定するには、Gitbook プラットフォームで組織の設定に移動します。 画像の例: shorturl.at/GNQR4

GitBook スペースは、デフォルトで HTTPS が有効になっている独自の CDN 経由で提供されます。証明書は LetsEncrypt によって発行されます

サポート可能なドメイン:

  • サブドメイン: www.example.com
  • カスタム ドメイン: docs.example.com

-- Gitbook を GitHub と同期して、両方のプラットフォームで効果的に編集できるようにする方法。

GitHub との統合は非常に簡単です。GitBook のコンテンツを変更すると、その編集内容が GitHub リポジトリに push されます。逆に、GitHub リポジトリに push された commit は、GitBook 内にインポートされます。

GitHub インテグレーションを設定します。

  • GitBook プラットフォーム内のスペースで、[Integrations] タブ > [GitHub] をクリックします。
  • 組織にリンクされている GitHub アカウントへのアクセスを GitBook に許可する
  • 組織の GitHub に移動し、「ハンドブック」のリポジトリを作成します（例: chaoss-handbook）。
  • 次に、GitBook プラットフォームの認証オプションで、接続する chaoss-handbook という名前のリポジトリを選択します。

これらの手順が完了すると、GitBook は chaoss-handbook リポジトリに Webhook を追加します。これにより、リポジトリの変更ごとにコンテンツを取得できるようになります。GitBook に変更を加えると、新しいコメントが push されます。

これで完了です。誰でも GitBook または GitHub リポジトリから編集を続行できます。

-- GitBook プラットフォームでページを編集する方法

GitBook プラットフォーム内で何かを編集するには、招待リンクまたは参加リンクを使用して GitBook プラットフォームに参加する必要があります。GitBook は、ユーザーがページ内に直接書き込むことができるビジュアル編集をサポートしています。

下書きは、作成者が編集できるユーザー コンテンツのバージョンです。作成者がアクセスできる唯一のバージョンで、作成を開始すると自動的に作成されます（エディタで最初の文字を入力する、新しいページを作成する、写真をアップロードするなど）。

下書きに加えた変更は下書きにのみ適用されるため、ユーザーは競合を発生させることなく、他のメンバーと同時に同じドキュメントに貢献できます。これを非同期編集と競合解決と呼びます。

最初のバージョンの下書きは、すぐに公開できるとは限りません。後で作業を続行する場合や、コンテンツを「統合」する準備がまだできていない場合は、「保存」を使用します。

編集が完了したら、下書きを「統合」できます。作成したコンテンツや行った変更は、チームメンバーや一般ユーザーが利用できるようになります。

画像の例: shorturl.at/gATZ8、shorturl.at/qrE57

-- コンテンツの構成:

目次: 各スペースには、ドキュメントの作成に必要な数のページを含めることができます。これらのページはすべて、画面の左側に目次として表示されます。目次では、ページの管理（新しいページ、ページのグループの作成、外部リンクの追加、バリエーションの追加）、外部ドキュメントのインポート（ウェブサイト、Markdown（.md または .markdown）、HTML（.html）、Microsoft Word（.docx）のファイルなど）を行うことができます。

最初のページ: 最初のページは、ドキュメントのホームページまたはルートであり、基本的にはドキュメントのすべてのページのマスターとして機能します。ドキュメントとスペースのメイン エントランスであるため、このページは移動、削除、子ページの作成、グループへの追加はできません。

ページ: ページにはタイトルがあり、エディタの上部に説明を追加できます。ページには、あらゆる種類のコンテンツを作成して追加できます。ページをネストするには、ページを別のページの下にドラッグ＆ドロップします。ページの子ページは非表示になりますが、閉じることができます。

外部リンク: 外部リンクのエントリ。エディタにコンテンツがありません。主な機能は外部ウェブサイトへのリンクです。

バリアント: バリアントを作成することで、ドキュメントの代替コンテンツを作成できます。これは、複数のバージョンの API、ライブラリ、翻訳を文書化する場合に便利です。

画像の例: shorturl.at/eyLW1、shorturl.at/rFRX6

-- ハンドブックはクライアント側でどのように表示されますか？

カオス コミュニティ ハンドブックはサブドメイン（https://docs.chaoss.community）からアクセスでき、ユーザー側では以下のような形式になります。

  • Mattermost ハンドブック - https://handbook.mattermost.com/
  • Linux Foundation Community Bridge Docs - https://docs.linuxfoundation.org/docs/ その他多数

プロジェクトのタイムライン:

1）コミュニティ ボンディング フェーズ（8 月 17 日～ 9 月 13 日）

A.) 第 1 ～ 4 週:

  • プロジェクトについてメンターと話し合う
  • プロジェクト内のさまざまなセクションに必要な情報を調査して収集し、コミュニティに明確な質問をする
  • ハンドブックに使用するプラットフォーム（GitBook を推奨）をコミュニティで明確にし、セットアップする
  • ドキュメントの問題に協力する

2）ドキュメントの開発フェーズ（9 月 14 日～ 11 月 30 日）

A.) 第 5 週（9 月 14 日～ 9 月 20 日）

  • ドラフト」の「概要」セクション

B.) 第 6 週（9 月 21 日～ 9 月 27 日）

  • 「CHAOSS コミュニティのやり方」セクションの下書き

C.) 第 7 週（9 月 28 日～ 10 月 4 日）

  • [リーダーシップへの道] セクションの下書きを作成する
  • 「用語」セクションの下書きを作成する

D.) 第 8 週（10 月 5 日～ 10 月 11 日）

  • コミュニティのロードマップの下書きを作成する
  • 設計貢献に関するガイドラインの草案を作成する

E.) 第 9 週（10 月 12 日～ 10 月 18 日）

  • [ドラフトの開発] セクション

F.) 第 10 週（10 月 19 日～ 10 月 25 日）

  • 文章とアウトリーチのセクションのガイドライン

G.) 第 11 週（10 月 26 日～ 11 月 1 日）

  • [下書きの指標] セクション
  • ドラフトの CHAOSScon セクション

H.) 第 12 週（11 月 2 日～ 11 月 8 日）

  • 会議セクションを設計する

  • コミュニティの一般的なよくある質問の下書き

    I.) 13 週目（11 月 9 日～ 11 月 15 日）

  • GSoC ガイドラインに関するドラフト

J.) 第 14 週（11 月 16 日～ 11 月 22 日）

  • アウトリーチのガイドラインに関する下書きを作成

K.) 第 15 週（11 月 23 日～ 11 月 29 日）

  • 準備時間: ドキュメント全体の調整と改善

3）評価フェーズ（11 月 30 日～ 12 月 5 日）

A.) 第 16 週:

  • プロジェクト レポートの下書きを作成する
  • プロジェクトの評価に記入する

コミュニティでのやり取り

1）コミュニティへの参加とディスカッション。

私は 2020 年 4 月から CHAOSS コミュニティを閲覧し、コミュニティ メンバーや特定のプロジェクト メンター（Georg Link 氏と Armstrong Foundjem 氏）とさまざまなディスカッションに参加してきました。コミュニティ メンバーの間で関心を集めた議論の 1 つが「Proposing Gitbook as a platform for hosting Community Handbook」です。この議論は、CHAOSS アーカイブのメーリング リストのスレッド「Proposing Gitbook as a platform for hosting Community Handbook」で確認できます。毎週のコミュニティ コールにも参加しており、コミュニティに最新情報を伝えるのに役立っています。

2）このプロジェクトに必要な情報をどのように収集しますか？

このプロジェクトでは、コミュニティ全体のハンドブックを設定する必要があります。そのため、ハンドブック内でアクセスする必要がある情報は、コミュニティ メンバーから収集し、コミュニティ メンバーと話し合います。上でスケジュールを提案しましたので、それに沿ってコミュニティの絆を深める期間に必要な情報を話し合い、収集することができます。

CHAOSS に沿ってさまざまなセクションを調査し、メーリング リストのスレッドを継続します。要件に応じて、メンターやコミュニティに状況を明確にするための質問をしてみます。

簡潔なディスカッションを行うため、毎週の電話会議にも参加します。

3）プロジェクトの進捗状況や、プロジェクトの進行中に発生する可能性のある問題や質問について、コミュニティにどのように情報を提供しますか？

柔軟性と透明性を確保するため、疑問点についてはメーリング リストのディスカッションを通じてコミュニケーションを取るようにします。

週ごとの進捗状況をブログ投稿で共有します。スクラムのドキュメントと直面した課題が含まれます。これは、オープンソース組織内のより多くのユーザーにリーチするために、コミュニティのメーリング リスト自体で共有されます。

また、主な問題について適切な提案や議論を行うため、週に 1 回コミュニティ コールにも参加します。

また、利用可能な週次タスクを記載した Trello ボードも作成する予定です。メンターはこのボードを使って、現在取り組んでいる問題や対応中の機能について明確かつ簡潔に理解できます。

4）プロジェクトで行き詰まり、メンターがいない場合はどうしますか？

メンターの役割は、生徒にループの隅々まで説明することではなく、生徒を正しい方向に導くことだと考えています。プロジェクトの調査と実装は、生徒が単独で責任を負うものとします。そのため、最後の手段としてのみメンターに助けを求めます。

ただし、サポートが必要なときにメンターが不在または忙しい場合は、CHAOSS コミュニティ内で問題を共有します。何か問題が起きたら、誰かがサポートしてくれると思います。また、dev.to などのオンライン フォーラムやデベロッパー コミュニティでも問題を共有します。

また、CHAOSS コミュニティ内の毎週のヘルプコールに参加して、疑問点を解消することもできます。