Rocket.Chat プロジェクト

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

プロジェクトの概要

オープンソースの組織:
Rocket.Chat
テクニカル ライター:
ミスター ゴールド
プロジェクト名:
bot のドキュメント
プロジェクトの期間:
標準の長さ（3 か月）

プロジェクトの説明

プロジェクトの概要

chat bot は、現代のテクノロジーの最先端技術です。チャット ソフトウェアと bot の全体的な成長率、音声認識、自動化の増加により、把握しやすく使いやすい bot ドキュメントを作成する必要性が高まっています。

包括的で明確なドキュメントを作成することがさらに重要になるため、既存の bot のドキュメントに簡単にアクセスして操作しやすくし、サポートされている各フレームワークの統一された詳細な手順と広範な例を提供する必要があります。また、冗長でわかりにくい情報を取り除くために整理する必要があります。

このプロジェクトの目標は、知識の格差を埋め、経験の浅い開発者が最先端テクノロジーのメリットを活かせるユーザーに提供できるよう後押しすることです。これは、Rocket.Chat で独自の bot を開発する際の合理的なエクスペリエンスを bot ビルダーに提供することで実現できます。この目標は、Rocket.Chat を、これらの開発者が chatbot のアイデアのイノベーション、作成、テストに好まれるオープンソース プラットフォームにすることを目的としており、最終的な BOT デプロイ ターゲットに関係なく行います。

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

bot のドキュメントに関連する最も重要な問題は次のとおりです。

  1. bot に関する直観的でなく、フレンドリーな一般的な情報
  2. bot のアーキテクチャに関連する、散在した冗長なセクション
  3. 「スタートガイド」手順が整理されておらず、信頼できる唯一の情報源がない
  4. 手順が欠如している、または手順の詳細が過剰である
  5. 暗黙的であいまいな bot SDK のドキュメント

プロジェクトの提案

本プロジェクトの目標と上記の問題を踏まえ、提案する機能強化のリストを以下に示します。

  1. bot のドキュメントを更新します。最初の導入をスムーズかつ一貫性のあるものにするため、次のドキュメントを更新して、シンプルなものから複雑なものへと段階的に移行する必要があります。

    • bot の概要: https://rocket.chat/docs/bots/
    • bot のアーキテクチャ: https://rocket.chat/docs/bots/bots-architecture/
    • bot 環境の構成: https://rocket.chat/docs/bots/configure-bot-environment/
    • bot のホームページ: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. bot のインストールに関するドキュメントを整理、統合する。すべてのサブプロジェクトに、bot リポジトリのクローンを作成して必要な依存関係をインストールする方法、すぐに開始する方法、初回起動後の bot の操作方法、デプロイ方法に関する統一された手順が必要です。

  3. Rocket.Chat JS SDK ドキュメントのプレゼンテーションを更新。SDK ドキュメントは、専用のツールを使用してソースコードからプログラムで生成する必要があります。この改善により、手法（またはその中の要素）が変更されるたびに GitHub 上のドキュメントを手動で更新する必要がなくなり、読みやすさが向上します。

タイムライン

応募の審査期間: コミュニティや共同作業者について理解を深めます。コミュニティ貢献ガイドとベスト プラクティスをご確認ください。最初の投稿を行いましょう。

コミュニティの絆: コミュニティを探索する。bot のドキュメントの現在の状態を調べます。弱点を特定する

1 週目: bot の新しいビジョンについてメンターと認識を合わせます。ビジョンに沿って、新しい bot ホームページ用に更新したコンテンツを作成します。

第 2 週: bot の概要、アーキテクチャ、環境の構成に関するページの改訂

3 週目 - メインのドキュメントに転送するサブプロジェクト（bot の GitHub リポジトリ）のリストを定義します。 - 移行後の bot ウェブサイトの動作を定義します。 - これらのリポジトリ内の情報を整理するために使うテンプレートを定義します。- 移行に関する主なドキュメントを準備する

4 週目: bBot リポジトリを転送する。定義済みのテンプレートに従って情報を整理する

第 5 週: Hubot リポジトリを転送する。定義済みのテンプレートに従って情報を整理する

第 6 週: Botkit リポジトリを転送する。定義済みのテンプレートに従って情報を整理する

7 週目: Rasa リポジトリを転送します。定義済みのテンプレートに従って情報を整理する

第 8 週: BotPress リポジトリを転送する。定義済みのテンプレートに従って情報を整理する

第 9 週: bot のすべてのサブプロジェクトを移行した後の、主要なドキュメントの構成とページの確定

10 週目: JSDoc の構成を確認する。JSDoc アーティファクトを保存する場所を定義します。ドライバ メソッドの文書化を開始する

第 11 週: ドライバ メソッドの文書化を完了する

12 週目: 結果の評価

マイルストーンの詳細

申請の審査期間

時間の前半は、コミュニティ チャンネルとソースコードをチェックし、プロジェクトの担当者に連絡を取ります。

期間の後半では、寄付の文化全般の確認と、投稿ガイドとベスト プラクティスの調査を行います。最初の投稿で、フローの仕組みを確認します。

コミュニティの絆

この時間は、ドキュメント リポジトリとそのロードマップを詳しく調べるために使われます。その情報に基づいて、改善できる弱点（例: 不完全な部分や欠落している部分）を特定できます。ギャップを埋めるために、可能であれば pull リクエストを作成します。

第 1 週～第 2 週

第 1 週は、bot に関するドキュメントの新しいビジョンについて調整するために、メンターとのコミュニケーションに重点を置きます。この情報は、bot の概要とその動作原則の概要を読者に説明することを目的とした、改訂版ドキュメントに含まれます。

第 2 週は、ビジョンに沿った新しい bot のホームページ用のコンテンツを作成し、Bots Overview、Architecture、Configuration of Environment の各ページを改訂します。

改訂後のドキュメントでは、以下の点をより明確にしています。 - 独自の bot を作成したい新しいデベロッパー - 無料で使いやすいプラットフォームを使用して bot を設計、コーディング、テストしたい、または既存の bot をそのプラットフォームに適応させたいと考えているプロ [bot] デベロッパー - Rocket.Chat 用の bot を作成したい、フレームワークの好みを持つプロの bot デベロッパー

作業範囲は次のとおりです。

  1. 重複するセクションを削除します。 たとえば、次のセクションでは重複する情報が共有されます。
    • bot はどのようにメッセージを送受信していますか。bot の概要（https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages）
    • Message Stream in Bots Architecture（https://rocket.chat/docs/bots/bots-architecture/#message-streams）
    • 「Creating Bot Users」(https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot)で、ボットと対話します。

  2. bot の概要ページのセクションとフレーズを修正して、DRY の原則に沿った bot のエコシステムと機能を明確に説明する。

    「舞台裏」の情報に関するセクションやフレーズを改訂します。

    • 技術的な観点から見た bot とは
    • 構成要素
    • これらのコンポーネントの連携の仕組み

  3. bot の作成に必要な手順を説明するクイック スタートガイドを作成します（参考資料として、「bot 環境の構成」へのリンクを含めます）。このガイドは [Configuration of Environment] ページにあります。

このようにして、デベロッパーは bot の性質と bot の能力について明確なビジョンを持つことになります。この時点で、デベロッパーは最初の bot を作成できるようになります。

成果物: bot のエコシステムとアーキテクチャに関する情報が記載された、改訂されたわかりやすい導入ガイド。

第 3 ～ 9 週

第 3 ～ 9 週は、GitHub リポジトリにまたがるすべての bot ドキュメントを統合し、それらのドキュメントをメインのドキュメント（https://rocket.chat/docs/bots/）に転送することに重点を置きます。これらのアクティビティは、いくつかのイテレーションに分けることができます。

  1. 定義

    メインのドキュメントに移行する必要がある bot サブプロジェクトのリストを定義する。転送後に bot ウェブサイトがどのように機能するかを定義します（一部の bot、bbot（http://bbot.chat など）には、github に加えてドキュメントを含む別のサイトがあります）。

  2. テンプレート

    ステップ 1 で定義した bot サブプロジェクト内の情報を整理するためのテンプレート（1 つの方法）を定義して作成します。このテンプレートは次のようになります。

    a. リポジトリのクローンを作成する

    b. 依存関係をインストールする

    c. bot を構成する

    d. bot を実行する

    e. 詳細構成

    f. 次のステップ

    重要でない出力を含むコマンド（「run a bot」など）については、Term Sheets ツール（https://neatsoftware.github.io/term-sheets/）を使用して、その出力のライブ プレゼンテーションを添えてください。

    さらに、初期の「クイック スタート」段階（ステップ a ～ d）をわかりやすくするため、すべてのステップが 1 つのライブ プレゼンテーションに統合されます。

    初心者が潜在的な障害から身を守れるように、（Rocket Chat エコシステムの一部として Glitch を使用して）プレイグラウンド環境を用意する必要があります。ここでは、初心者が内部に「サンプルコード」を持つ bot とチャットできる環境を用意する必要があります。

  3. 準備

    転送に関する主なドキュメントを準備する。これには、適切なフォルダとページ構造を作成し、その構造に沿って目次を調整することも含まれます。

    最終的な構造は次のようになります。

    • bot
      • bot のアーキテクチャ
      • bot ユーザーを作成する
      • bot 環境の構成
      • bot の実行
        • Bbot
        • Hubot bot
        • botkit bot
        • Rasabot
        • botpress bot

  4. 移行

    定義済みの bot サブプロジェクトをメインのドキュメントに 1 つずつ移行します。bot のドキュメントの各部分には、現在のバージョン（bBot の実行など）のようなサブセクションを含む個別のページがあります。

    • bot の実行
      • Bbot
      • Hubot bot
      • botkit bot
      • Rasabot
      • botpress bot

  5. 組織

    いくつかのアクティビティがあります。

    1. ステップ 2 で定義したテンプレートに従って、各 bot GitHub リポジトリの情報を整理します。
    2. すべての bot サブプロジェクトに関連する共通のコンポーネント（環境変数など）を、メインのドキュメントの階層の 1 つ上のレベルに移動し、bot のサブプロジェクトをこれらのコンポーネントにリンクする
    3. サポートされているフレームワークごとに「Hello World」bot のサンプルを作成する。この例は、Rocket.Chat の「スタートガイド」bot として使用されます。

これが重要な理由は？ Rocket.Chat でサポートされている alexa、hubot、chatops-gitsy、botpress、rasa、bbot、botkit、BOTswana、hubot-gitsy の 8 つのサブプロジェクトはすべて、開発者の README の形式でドキュメントが散らばっています。これらの README には、構造がまったくない、開始方法について古い情報が含まれている、情報が多すぎる (Docker を使用して bot を実行する方法について hubot（https://github.com/RocketChat/hubot-rocketchat）のように 3 つの冗長になる場合があります)、環境変数を含むテーブルなどが含まれています。

このような側面は、新規の開発者にとって、非常に詳細なレベルでの混乱を招きます。その結果、デベロッパーは、わずかなターミナル コマンドだけで bot を稼働させることができなくなります。

転送と最適化が完了すると、GitHub の既存の bot リポジトリに、メイン ドキュメントを参照する README ファイルが追加されます。

次のような利点があります。 - 開発者が新しい bot を使い始めるのが容易になる統合構造 - bot に関するドキュメントの信頼できる唯一の情報源 - 統一された構造により、あらゆる bot に関する必要な情報を簡単に見つけられるようになる

成果物: Rocket.Chat でサポートされている bot を作成、構成、実行する方法に関する、わかりやすい手順が 1 か所（メインのドキュメント）にまとめられています。

第 10 週

今週は、インライン コメントの価値を最大化するための JSDoc（https://devdocs.io/jsdoc/）の構成に焦点を当てます。これには次のものが含まれます。

  1. ドライバ メソッドのコメントを解析するように JSDoc が適切に構成されていることを確認する（https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods）
  2. postman-jsdoc-theme（https://github.com/postmanlabs/postman-jsdoc-theme）をインストールして、生成される HTML 出力をより明示的かつデベロッパーにとってわかりやすいものにする
  3. JSDoc ドキュメント アーティファクトが公開される場所を定義する
  4. ドライバのメソッドに関連するすべての関数（dist/lib/driver.js ファイル）を記述します。これには、次が含まれます。
    • メソッドの説明の追加/編集
    • メソッド パラメータの説明の追加/編集
    • メソッド リクエストの例の追加/編集（該当する場合）
    • メソッド レスポンスの例を追加または編集する（該当する場合）

デベロッパーにとってはインライン ドキュメントの方が簡単に作成、保守でき、その自動生成メカニズムにより、SDK メソッドを変更するたびに個別に更新する必要がある GitHub（https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods）でホストされている静的ドキュメントが不要になります。

第 11 週

今週は、ドライバーのメソッドの説明を最終決定することに専念します。完成後、説明の正確性と一貫性がテストされ、新しいドキュメントが世界中に公開されます。

第 12 週

完了した作業の最終処理。承認チェック。