Rocket.Chat 專案

本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。

專案摘要

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

Project description

專案摘要

Chat 機器人採用當今技術的尖端。即時通訊軟體和機器人的整體成長率，以及語音辨識和自動化功能在日益增加，這也表示他們需要製作容易掌握且使用的機器人說明文件。

提供清楚詳盡的文件變得更加重要，因此現有的機器人文件必須更易於存取和瀏覽，且應針對每個受支援的架構，提供整合式逐步操作說明，以及詳盡的範例。此外，這個 API 還應做好清除，以免冗餘且難以理解的資訊。

本專案的目標是消弭知識落差，並鼓勵經驗較不豐富的新開發人員，將先進技術的好處提供給充滿熱情的目標對象。因此我們在 Rocket.Chat 中為機器人建構者提供簡便的使用體驗，讓開發者能夠輕鬆打造機器人。這項目標旨在讓 Rocket.Chat 成為更受歡迎的開放原始碼平台，無論最終的 BOT 部署目標為何，這些開發人員都能透過這個平台推動創新、製作及測試自己的聊天機器人構想。

專案問題

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

  1. 非直覺易懂的一般資訊
  2. 與機器人架構相關的散佈和冗餘區段
  3. 內容經過整理的「入門指南」操作說明，但缺乏單一資料來源
  4. 缺乏操作說明或解說內容過多
  5. 「隱含和不清楚的 Bot SDK」說明文件

專案提案

根據專案目標和上述問題，提議的強化項目如下：

  1. 更新機器人說明文件。為了讓初始介紹的流程更加流暢一致，更新下列文件時，應逐步從簡單到更複雜的方式更新：

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

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

  3. Revise Rocket.Chat JS SDK 說明文件簡報。您必須使用特殊工具，以程式輔助方式從原始碼產生 SDK 說明文件。這項改善措施將使資料的可讀性化，讓開發人員不必在每次方法 (或當中的內容) 變更時，手動更新 GitHub 上的文件。

賽況

申請審查期間：熟悉社群和合作對象。瞭解社群協力指南與最佳做法。第一個貢獻的內容。

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

第 1 週：與導師討論機器人新願景。根據願景為新版機器人首頁建立更新內容。

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

第 3 週 - 定義應轉移至主要說明文件的子專案 (機器人 GitHub 存放區) 清單。- 定義機器人網站在轉移後應如何運作。 - 定義一個範本，以便整理這些存放區中的資訊。 - 備妥主要移轉文件

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

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

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

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

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

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

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

第 11 週：完成記錄驅動程式方法

第 12 週：評估結果

里程碑詳細資料

申請審查期間

在這段期間，我們會致力檢查社群頻道和原始碼，以及與專案相關人員聯絡。

活動期間的後半段會著重確認貢獻文化、審查貢獻指南和最佳做法。這會是第一次貢獻內容，以便瞭解流程的運作方式。

社群凝聚力

屆時我們會深入探討說明文件存放區及藍圖。根據這項資訊，或許就能找出需要改善的不足點 (例如不完整或缺漏的部分)。如果可以，請建立提取要求來填補缺口。

第 1 週 - 第 2 週

第一週的重點是與導師溝通，討論機器人技術文件的新願景。這些資訊將納入修訂版文件中，旨在讓讀者概略瞭解機器人的用途和運作原則。

第二週是根據願景和修改機器人首頁的願景、架構、環境設定頁面，為新的機器人首頁製作內容。

修訂過的文件將更加聚焦於以下層面： - 想要自行開發機器人的新開發人員 - 想要使用簡單易用的免費平台來設計/編寫/測試機器人，或配合該平台適應現有機器人的專業 [機器人] 開發人員 - 專業的機器人開發人員，提供想要為 Rocket 開發機器人的架構偏好設定。

工作範圍如下所示：

  1. 移除多餘區段。 舉例來說，下列區段會共用重疊的資訊：
    • 機器人如何收發訊息？「機器人總覽」(https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • 機器人架構中的訊息串流 (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • 在「建立機器人使用者」中與機器人交談 (https://rocket.chat/docs/bots/create-bot-users/#talk-to-your-bot)

  2. 修改「機器人總覽」頁面的區段和詞組，清楚描述機器人生態系統和功能，並依 DRY 原則。

    修改與「背景」相關的資訊：

    • 從技術層面說明機器人的意義
    • 組成元件
    • 這些元件如何搭配運作

  3. 撰寫快速入門指南，說明建立機器人的必要步驟 (並附上「設定機器人環境」連結，可參閱更多說明)。本指南位於「環境設定」頁面下方。

這樣一來，開發人員就能明確掌握機器人的性質，並掌握機器人能執行哪些操作。從這時開始，開發人員就能建立第一個機器人。

交付項目：提供易於理解的簡介指南，其中提供機器人生態系統和架構的相關資訊。

第 3 至 9 週

第 3 週至第 9 週的時間專門負責統合 GitHub 存放區中的所有機器人文件，並將這些文件轉移至主要說明文件 (https://rocket.chat/docs/bots/)。這些活動可以分成多次：

  1. 定義

    定義應遷移至主要說明文件的機器人子專案清單。定義機器人網站在轉移後的運作方式 (部分機器人、bbot，例如 (http://bbot.chat)) 除了提供 github 之外，另外也有說明文件。

  2. 範本

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

    a. 複製存放區

    b. 安裝依附元件

    c. 設定機器人

    d. 執行機器人

    e. 進階設定

    f. 其他步驟

    包含某些非微型輸出內容的指令 (例如「run a bot」) 應一併使用 Term 試算表工具 (https://neatsoftware.github.io/term-sheets/) 即時呈現該輸出內容。

    此外，為了讓初始的「快速入門」階段 (步驟 a - d) 更清楚明瞭，所有步驟都會彙整成一份即時簡報。

    為了讓新手感到安心，避免可能失敗，應在 Playground 環境中提供程式碼範例 (使用 Glitch 做為 Rocket Chat 生態系統的一部分)，新加入的玩家可以與在現實中發現「範例程式碼」的機器人交談。

  3. 準備

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

    最終結構可能如下所示：

    • 機器人
      • 機器人架構
      • 建立機器人使用者
      • 設定機器人環境
      • 執行機器人
        • 機器人機器人
        • 哈伯特機器人
        • Botkit 機器人
        • 拉薩波特
        • 機器人瓶

  4. 遷移

    將已定義的機器人子專案逐一遷移至主要說明文件。每段機器人說明文件都有單獨的頁面，其中包含類似現行版本 (例如執行 bBot) 的子區段。

    • 執行機器人
      • 機器人機器人
      • 哈伯特機器人
      • Botkit 機器人
      • 拉薩波特
      • 機器人瓶

  5. 機構

    分為以下幾項活動：

    1. 根據第 2 步驟中定義的範本，整理每個機器人 GitHub 存放區中的資訊。
    2. 將與所有機器人子專案相關的常見元件 (例如環境變數) 移到主要說明文件的階層中，並將機器人子專案連結至這些元件
    3. 為每個支援的架構建立「hello world」機器人範例。本範例將做為 Rocket.Chat 的「入門」機器人。

為何這如此重要？ Rocket.Chat 支援全部 8 個子專案：alexa、Hubot、chatops-gitsy、botpress、rasa、bbot、botkit、BOTswana、hubot-gitsy 和 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 中)。這包括：
    • 新增/編輯方法說明
    • 新增/編輯方法參數的說明
    • 新增/編輯方法要求的範例 (如適用)
    • 新增/編輯方法回應範例 (如適用)

內嵌說明文件能以開發人員的角度輕鬆撰寫及維護，而自動產生的生成機制可讓您移除 GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)，每次使用 SDK 方法時，都必須個別更新這些說明文件。

第 11 週

本週將完全負責說明駕駛方法的最終成果。完成後，我們會測試這些說明的準確性和一致性，接著就會向全世界發布新的說明文件。

第 12 週

完成工作的最終成果。接受檢查。