Rocket.Chat 專案

本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。

專案摘要

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

Project description

專案摘要

Chat 機器人一直是現今技術最先進的技術。即時通訊軟體和機器人的整體成長率極高，加上語音辨識和自動化技術的增長率，因此影響了建立簡單易用的機器人說明文件需求。

提供詳盡且清楚的說明文件就顯得格外重要，因此現有的機器人說明文件需要更容易存取和瀏覽，且應該針對每種支援的架構提供整合式逐步操作說明和豐富的範例。此外，也要仔細刪減多餘且難以理解的資訊。

本專案的目標是消除知識差距，並鼓勵經驗較少的新開發人員實現頂尖技術的優勢，進而吸引充滿期待的目標對象。方法是為機器人建構工具提供在 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. 修訂 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 週

第一週將致力於與導師溝通，以達成機器人說明文件的新願景。修訂版文件中旨在向讀者概略說明機器人的定義和工作原則。

第二週我們要分享新機器人首頁內容，並以願景為基礎修改機器人總覽、架構、環境設定。

修訂後的文件將著重於： - 新開發人員想要自行打造機器人 - 專業 [機器人] 開發人員，想要透過容易使用的平台設計/程式碼/測試機器人，或根據該平台調整現有機器人 - 擁有架構偏好設定的專業機器人開發人員

工作範圍如下：

  1. 移除多餘的版面。 舉例來說，下列部分會共用重疊的資訊：
    • 機器人如何收發訊息？機器人總覽 (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • 機器人架構中的訊息串流 (https://rocket.chat/docs/bots/bots-frameworkure/#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. 範本

    定義及建立範本，以便整理您在第一個步驟中定義的機器人子專案內的資訊。這個範本的外觀如下：

    a. 複製存放區

    b. 安裝依附元件

    c. 設定機器人

    d. 執行機器人

    e. 進階設定

    f. 其他步驟

    包含一些不重要的輸出內容 (例如「執行機器人」) 的指令應透過「字詞試算表」工具 (https://neatsoftware.github.io/term-sheet/) 即時呈現。

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

    為了讓新手可以安心嘗試，建議您提供模擬環境 (使用 Glitch，也就是 Rocket Chat 生態系統的一部分) 提供的程式碼範例，讓新手能與擁有「範例程式碼」的機器人聊天。

  3. 準備

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

    最終結構應如下所示：

    • 機器人
      • 機器人架構
      • 建立機器人使用者
      • 設定機器人環境
      • 執行機器人
        • 機器人機器人
        • 休旅車
        • 機器人機器人
        • Rasa Bot
        • 機器人

  4. 遷移

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

    • 執行機器人
      • 機器人機器人
      • 休旅車
      • 機器人機器人
      • Rasa Bot
      • 機器人

  5. 機構

    並分為數個活動：

    1. 根據第 2 步驟中定義的範本，整理各個機器人 GitHub 存放區中的資訊。
    2. 將與所有機器人子專案相關的常用元件 (例如環境變數) 移至主要說明文件階層的上一層，並將機器人子專案連結至這些元件
    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) 以及含有環境變數的 Hubot，例如 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. 說明與驅動程式方法相關的所有函式 (in dist/lib/driver.js) 檔案。這包括：
    • 新增/編輯方法說明
    • 新增/編輯方法參數的說明
    • 新增/編輯方法要求範例 (如適用)
    • 新增/編輯方法回應範例 (如適用)

從開發人員的角度來看，內嵌說明文件更容易撰寫及維護，其自動產生的機制則可讓您移除 GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) 代管的靜態說明文件，且 SDK 方法中的各項變更必須分別更新。

第 11 週

本週將完全專注於描述駕駛方法的最終成品。完成後，我們就會測試說明的準確性和一致性，然後才會將新版文件發布到全世界。

第 12 週

已完成工作。接受檢查。