Rocket.Chat プロジェクト

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

プロジェクトの概要

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

プロジェクトの説明

プロジェクトの概要

チャットボットは、最新のテクノロジーです。チャット ソフトウェアとボットの全体的な成長率が非常に高く、音声認識と自動化の増加に伴い、理解しやすく使いやすいボット ドキュメントを作成する必要性が高まっています。

包括的で明確なドキュメントの重要性がさらに高まるため、既存のボット ドキュメントは、アクセスとナビゲーションを容易にし、サポートされている各フレームワークの統一された手順と豊富な例を提供する必要があります。また、冗長な情報やわかりにくい情報を削除して整理する必要があります。

このプロジェクトの目標は、知識のギャップを埋め、経験の浅い新規のデベロッパーにも最先端のテクノロジーのメリットを活かせるようなオーディエンスに働きかけることです。これは、bot 作成者が Rocket.Chat で独自の bot 開発を効率的に行えるよう支援することで実現できます。この目標は、最終的な BOT のデプロイ先に関係なく、デベロッパーがチャットボットのアイデアを革新、作成、テストするためのオープンソース プラットフォームとして Rocket.Chat を推奨することを目指しています。

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

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

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

プロジェクトの提案書

プロジェクトの目標と上記の問題に基づき、提案される機能強化は次のとおりです。

  1. ボットのドキュメントを更新しました。最初の導入をスムーズかつ一貫したものにするには、次のドキュメントを更新して、簡単なものから複雑なものへと段階的に切り替える必要があります。

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

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

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

タイムライン

応募審査期間: コミュニティや一緒に仕事をする人々について理解を深めます。コミュニティ貢献に関するガイドとベスト プラクティスをご確認ください。最初の拠出を行う。

コミュニティの結びつき: コミュニティを探索します。ボット ドキュメントの現在の状態を確認します。弱点を特定する。

1 週目: ボットの新しいビジョンについてメンターと連携します。ビジョンに沿って、新しい Bots ホームページの更新コンテンツを作成します。

2 週目: [Bots Overview]、[Architecture]、[Configuration of Environment] のページを復習する

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

第 4 週: bBot リポジトリを移行します。定義されたテンプレートに従って情報を整理する

5 週目: Hubot リポジトリを移行します。定義されたテンプレートに従って情報を整理する

週 6: Botkit リポジトリを移行します。定義されたテンプレートに従って情報を整理する

週 7: Rasa リポジトリを移行します。定義されたテンプレートに従って情報を整理する

週 8: BotPress リポジトリを移行します。定義されたテンプレートに従って情報を整理する

週 9: すべてのボット サブプロジェクトを移行した後、メインのドキュメント構造とページを確定

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

週 11: ドライバ メソッドのドキュメント化を完了する

12 週目: 結果を評価する

マイルストーンの詳細

申請審査期間

最初の期間は、コミュニティ チャンネルとソースコードの確認、プロジェクトに専念している担当者への連絡に充てられます。

残りの期間は、貢献文化全般の確認、貢献ガイドとベスト プラクティスの確認に充てられます。この時点で、初めての投稿でフローの仕組みを確認できます。

コミュニティの結びつき

今回は、ドキュメント リポジトリとそのロードマップを詳しく見ていきます。その情報に基づいて、改善できる弱点（部品の不足や欠落など）を特定できます。pull リクエストを作成して（可能な場合）、ギャップを埋めます。

第 1 週～第 2 週

最初の 1 週間は、Bots ドキュメントの新しいビジョンを一致させるために、メンターとのコミュニケーションに専念します。この情報は、ボットとその仕組みの概要を読み手に提供することを目的とした改訂版ドキュメントの一部となります。

2 週目は、ビジョンに沿って新しい Bots ホームページのコンテンツを作成し、[Bots の概要]、[アーキテクチャ]、[環境の構成] のページを改訂します。

改訂されたドキュメントでは、次の対象に明確に焦点を当てています。 - 独自の bot を作成する新しいデベロッパー - 無料の使いやすいプラットフォームを使用して bot を設計、コード化、テストする、または既存の bot をそのプラットフォームに適応させるプロの [bot] デベロッパー - フレームワークを好むプロの bot デベロッパーで、Rocket.Chat 用の bot を作成する

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

  1. 重複するセクションを削除します。たとえば、次のセクションは重複する情報を共有しています。
    • bot はどのようにしてメッセージを送受信するのでしょうか。Bot の概要（https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages）
    • Bot アーキテクチャのメッセージ ストリーム（https://rocket.chat/docs/bots/bots-architecture/#message-streams）
    • ボットユーザーの作成（https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot）で bot に話しかけます

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

    「内部情報」に関するセクションとフレーズを改訂しました。

    • 技術的な観点から見た bot とは
    • 構成要素
    • コンポーネントの連携方法

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

こうすることで、開発者は bot の性質と、bot で何ができるかについて明確なビジョンを持つことができます。その後、デベロッパーは最初の bot を作成できるようになります。

成果物: ボット エコシステムとアーキテクチャに関する情報を含む、わかりやすい改訂版の入門ガイド。

第 3 ～ 9 週

3 ～ 9 週目は、GitHub リポジトリ全体のすべてのボット ドキュメントを統合し、これらのドキュメントをメインのドキュメント（https://rocket.chat/docs/bots/）に移行することに専念します。これらのアクティビティは、いくつかのイテレーションに分けることができます。

  1. 定義

    メイン ドキュメントに移行すべき bot サブプロジェクトのリストを定義する。移行後の bot ウェブサイトの動作を定義します（一部の bot（bbot など（http://bbot.chat））には、GitHub に加えてドキュメントが掲載されている個別のサイトがあります）。

  2. テンプレート

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

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

    b. 依存関係のインストール

    c. bot を構成する

    d. bot を実行する

    e. 詳細構成

    f. 次のステップ

    出力が複雑なコマンド（「bot を実行する」など）には、Term Sheets ツール（https://neatsoftware.github.io/term-sheets/）を使用して、その出力をライブで表示する必要があります。

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

    新規ユーザーが潜在的な障害から安心できるように、コードのサンプルを遊び場環境（Rocket Chat エコシステムの一部として Glitch を使用）で提供する必要があります。新規ユーザーは、内部に「サンプルコード」が組み込まれた bot とチャットできます。

  3. 準備

    移行に必要な主な書類を準備します。これには、適切なフォルダとページの構造の作成、およびその構造に応じた目次の調整が含まれます。

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

    • bot
      • bot のアーキテクチャ
      • ボットユーザーを作成する
      • bot 環境を構成する
      • bot を実行する
        • bBot Bot
        • Hubot Bot
        • botKit bot
        • ラサボット
        • Botpress bot

  4. 移行

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

    • bot を実行する
      • bBot Bot
      • Hubot Bot
      • botKit bot
      • ラサボット
      • Botpress Bot

  5. 組織

    以下のアクティビティがあります。

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

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

これらの要素は、（新規の）デベロッパーにとって非常に詳細で混乱を招きます。その結果、デベロッパーはいくつかのターミナル コマンドだけでは bot を起動できません。

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

これには、次のようなメリットがあります。 - デベロッパーが新しい bot を簡単に使い始められる統合構造 - bot に関する信頼できる唯一の情報源のドキュメント - 統合構造により bot に関する必要な情報が見つけやすくなる

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

第 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 内）を記述します。これには、次が含まれます。
    • メソッドの説明の追加/編集
    • メソッド パラメータの説明の追加/編集
    • メソッド リクエストの例の追加/編集（該当する場合）
    • メソッド レスポンスを追加または編集する（該当する場合）

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

第 11 週

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

第 12 週

完了した作業の確定。承認チェック。