Rocket.Chat プロジェクト

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

プロジェクトの概要

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

プロジェクトの説明

プロジェクトの概要

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

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

このプロジェクトの目標は、知識のギャップを埋め、経験の浅い新しい開発者が最先端のテクノロジーのメリットを活かせるよう支援することです。これは、Rocket.Chat で独自の bot を開発する際に、bot 構築者に合理的なエクスペリエンスを提供することで実現できます。この目標は、最終的な BOT デプロイ ターゲットに関係なく、Rocket.Chat を開発者が chatbot のアイデアを革新、作成、テストするための推奨オープンソース プラットフォームにすることです。

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

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 を操作する方法、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 週目: 結果の評価

マイルストーンの詳細

申請の審査期間

パート 1 では、コミュニティ チャンネルとソースコードのチェックと、プロジェクト専任の担当者への連絡を行います。

後半では、投稿ガイドとベスト プラクティスを交えて、投稿の文化全般の確認を行います。このときに、最初の投稿でフローの仕組みを確認します。

コミュニティの絆

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

第 1 週～第 2 週

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

第 2 週は、ビジョンに沿った新しい bot のホームページ用のコンテンツを作成し、Bot の概要、アーキテクチャ、環境の構成に関するページを修正します。

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

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

  1. 重複するセクションを削除します。 たとえば、次のセクションでは重複する情報が共有されます。
    • bot はどのようにしてメッセージを送受信するのですか？Bots の概要（https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages）
    • Bots アーキテクチャにおけるメッセージ ストリーム（https://rocket.chat/docs/bots/bots-architecture/#message-streams）
    • Bot ユーザーの作成（https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot）で、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 サブプロジェクト内の情報を整理するためのテンプレート（方法）を定義して作成する。このテンプレートは次のようになります。

    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 の実行
        • bot bot
        • ウボットボット
        • Botkit bot
        • Rasa Bot
        • Botpress Bot

  4. 移行

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

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

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

第 11 週

今週は、運転手のメソッドの説明の完成に全力を尽くします。完成後、説明の正確性と一貫性がテストされ、新しいドキュメントが世界中に公開されます。

第 12 週

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