Rocket.Chat 專案

本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。

專案摘要

開放原始碼組織：
Rocket.Chat
技術文件撰稿者：
Mister Gold
專案名稱：
機器人說明文件
專案長度：
標準長度 (3 個月)

Project description

專案摘要

Chatbot 是當今最先進的技術。由於聊天軟體和機器人的整體成長率極高，再加上語音辨識與自動化技術不斷攀升，這使得開發人員需要製作簡單易懂的機器人說明文件。

因此，我們更需要提供完整且清楚的說明文件，讓使用者更容易存取及瀏覽現有的機器人說明文件，並為每個支援的架構提供統一的逐步操作說明和大量範例。另外，也應整理內容，移除冗餘且難以理解的資訊。

這個專案的目標是縮小知識落差，並鼓勵新手開發人員運用新技術，為熱情的使用者帶來更多好處。為此，我們為機器人開發人員提供簡化體驗，讓他們在 Rocket.Chat 中開發自己的機器人。這項目標旨在讓 Rocket.Chat 成為開發人員的首選開放原始碼平台，無論最終的 BOT 部署目標為何，都能在此創新、建立及測試聊天機器人構想。

專案問題

以下列出與機器人說明文件相關的最重要問題：

  1. 機器人的一般資訊不直覺且不友善
  2. 與機器人架構相關的散佈圖和備援區塊
  3. 「入門指南」說明不夠完整，且缺乏單一可靠資料來源
  4. 缺少操作說明或操作說明過於詳細
  5. 隱含且含糊的 Bot SDK 說明文件

專案提案

根據專案目標和上述問題，以下列出建議的強化功能：

  1. 更新 Bot 說明文件。為了讓初始介紹順暢且一致，請更新下列文件，從簡單到複雜逐步轉換：

    • 機器人總覽：https://rocket.chat/docs/bots/
    • 機器人架構：https://rocket.chat/docs/bots/bots-architecture/
    • 設定機器人環境：https://rocket.chat/docs/bots/configure-bot-environment/
    • 機器人首頁：https://github.com/RocketChat/rocketchat.github.io/pull/

  2. 整理及整合機器人安裝說明文件。所有子專案都應提供一套統一的操作說明，說明如何複製機器人存放區並安裝必要的依附元件、如何快速上手、如何在首次啟動後使用機器人，以及如何部署機器人。

  3. 修訂 Rocket.Chat JS SDK 說明文件簡報。SDK 說明文件應透過程式輔助方式，使用專用工具從原始碼產生。這項改善措施可提升可讀性，並免除每次方法 (或其中的內容) 變更時，都必須手動更新 GitHub 文件的麻煩。

賽況

申請審查期間：熟悉社群和合作對象。瞭解社群貢獻指南和最佳做法。開始貢獻。

社群連結：探索社群。檢查機器人說明文件的目前狀態。找出弱點。

第 1 週：與導師討論 Bot 的新願景。根據願景，為新的 Bot 首頁建立更新內容。

第 2 週：修改機器人總覽、架構、環境頁面設定

第 3 週 - 定義應轉移至主要說明文件的子專案 (機器人 GitHub 存放區) 清單。- 定義機器人網站在轉移後的運作方式。- 定義用於整理這些存放區內資訊的範本。- 準備轉移作業的主要文件

第 4 週：轉移 bBot 存放區。依據定義的範本整理資訊

第 5 週：轉移 Hubot 存放區。依據定義的範本整理資訊

第 6 週：轉移 Botkit 存放區。依據定義的範本整理資訊

第 7 週：轉移 Rasa 存放區。依據定義的範本整理資訊

第 8 週：轉移 BotPress 存放區。依據定義的範本整理資訊

第 9 週：轉移所有機器人子專案後，完成主要文件結構和頁面

第 10 週：檢查 JSDoc 設定。定義儲存 JSDoc 構件的地點。開始記錄驅動程式方法

第 11 週：完成驅動程式方法的文件

第 12 週：評估結果

里程碑詳情

申請審查期間

期間的第一部分將專門負責檢查社群頻道和原始碼，以及聯絡專案專責人員。

研究期間的第二部分將致力於瞭解整體捐款文化，檢視捐款指南及最佳做法。這時可以透過首次貢獻內容，瞭解流程的運作方式。

社群經營

這次我們將深入探討說明文件存放區和路線圖。根據這些資訊，您可以找出需要改善的弱點 (例如缺少或不完整的部分)。建立可填補空白的提取要求 (如有可能)。

第 1 週 - 第 2 週

第一週將專注於與導師溝通，以便配合 Bot 說明文件的新願景。這項資訊將納入修訂版文件中，讓讀者瞭解什麼是機器人，以及其運作原理。

第二週將根據願景，為新的 Bot 首頁建立內容，並修訂「Bot 總覽」、「架構」和「環境設定」頁面。

修訂後的文件將更明確地著重於以下內容： - 想要建立自有機器人的新手開發人員 - 想要使用免費且易於使用的平台設計/編寫/測試機器人，或將現有機器人改用該平台的專業 [機器人] 開發人員 - 想要為 Rocket.Chat 建立機器人的專業機器人開發人員，並使用其偏好的架構

工作範圍如下：

  1. 移除多餘的部分。舉例來說，下列各節分享的是重疊資訊：
    • 機器人如何傳送及接收訊息？機器人總覽 (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Bots Architecture 中的訊息串流 (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • 在「建立機器人使用者」中與機器人對話 (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot)

  2. 修改「機器人總覽」頁面的各部分和詞組，清楚說明遵循剛果民主原則的漫遊器生態系統和功能。

    修訂有關「幕後」資訊的段落和詞彙：

    • 從技術層面來看，機器人是什麼
    • 包含哪些元件
    • 這些元件如何搭配運作

  3. 撰寫快速入門指南，說明建立機器人所需的步驟 (並附上「設定機器人環境」的連結，供讀者參考)。本指南位於「設定環境」頁面下方。

這樣一來，開發人員就能清楚掌控機器人的性質，以及機器人的功能。開發人員屆時就能建立第一個機器人。

交付項目：修訂且簡單易懂的介紹指南，提供機器人生態系統和架構的相關資訊。

第 3 週 - 第 9 週

第 3 到第 9 週將專門用來統合 GitHub 存放區中的所有機器人文件，並將這些文件轉移至主要說明文件 (https://rocket.chat/docs/bots/)。這些活動可分為幾個迭代：

  1. 定義

    定義應遷移至主要文件的機器人子專案清單。定義 bot 網站在轉移後的運作方式 (某些 bot，例如 bbot (http://bbot.chat) 除了 GitHub 外，還有其他網站提供說明文件)。

  2. 範本

    定義並建立範本 (一種方法)，用於在第 1 步驟中定義的機器人子專案中整理資訊。這個範本可能如下所示：

    a. 複製存放區

    b. 安裝依附元件

    c. 設定機器人

    d. 執行機器人

    e. 進階設定

    f. 後續步驟

    包含一些非簡單輸出的指令 (例如「執行機器人」)，應搭配使用「Term Sheets」工具 (https://neatsoftware.github.io/term-sheets/) 進行即時輸出展示。

    此外，為了讓初始的「快速入門」階段 (步驟 a 到 d) 更清楚，我們也會將所有步驟合併為一場直播簡報。

    為了讓新手不必擔心潛在的失敗問題，您應在遊樂場環境中提供程式碼範例 (使用 Glitch，做為 Rocket Chat 生態系統的一部分)，讓新手可以與機器人進行即時通訊，並在幕後使用「範例程式碼」。

  3. 準備

    準備轉移的主要文件。包括建立適當的資料夾和頁面結構，以及根據該結構調整目錄。

    最終結構可能如下所示：

    • 機器人
      • 機器人架構
      • 建立 Bot 使用者
      • 設定機器人環境
      • 執行機器人
        • bBot Bot
        • 胡伯特機器人
        • Botkit Bot
        • Rasa Bot
        • Botpress 機器人

  4. 遷移

    將已定義的機器人子專案逐一遷移至主要文件。每組機器人說明文件都有獨立頁面，內含目前版本等子區段 (例如執行 bBot)。

    • 執行機器人
      • bBot Bot
      • 胡伯特機器人
      • Botkit Bot
      • Rasa Bot
      • Botpress Bot

  5. 機構

    屆時將有以下幾個活動：

    1. 根據第 2 個步驟定義的範本，整理各個機器人 GitHub 存放區中的資訊。
    2. 將與所有 Bot 子專案相關的常見元件 (例如環境變數) 在主要文件的階層中向上移動一層，並將 Bot 子專案連結至這些元件
    3. 為每個支援的架構建立「Hello World」機器人範例。這個範例會用於 Rocket.Chat 的「開始使用」機器人。

為什麼這麼做很重要？Rocket.Chat 支援的所有 8 個子專案：alexa、hubot、chatops-gitsy、botpress、rasa、bbot、botkit、BOTswana、hubot-gitsy 都有散布在各處的開發人員 README 形式文件。這些 README 都沒有架構、包含入門教學的過時資訊，或包含過多資訊 (有時候，會介紹如何使用 Docker 執行機器人，例如 hubot (https://github.com/RocketChat/hubot-rocketchat) 以及包含環境變數的表格)。

這些面向讓開發人員 (做為新手) 的細節令人難以捉摸。因此，開發人員無法只透過幾個終端機指令啟動機器人。

轉移及最佳化完成後，GitHub 中現有的機器人存放區就會包含參照主要文件的 README 檔案。

這樣的好處如下： - 統一的架構可讓開發人員輕鬆開始使用新的機器人 - 提供機器人說明文件的單一可靠資料來源 - 採用統一架構，您就能更輕鬆地找到任何機器人的必要資訊

成果：在單一位置 (主要說明文件) 下，提供簡單易懂的操作說明，說明如何建立、設定及執行 Rocket.Chat 支援的機器人。

第 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 週

完成工作並完成結算。驗收檢查。