Rocket.Chat 项目

本页面包含 Google 文档季接受的技术写作项目的详细信息。

项目摘要

开源组织：
Rocket.Chat
技术文档工程师：
Mister Gold
项目名称：
聊天机器人文档
项目时长：
标准时长（3 个月）

Project description

项目摘要

聊天机器人是当今最前沿的技术。聊天软件和聊天机器人的整体增长率非常高，语音识别和自动化技术也越来越普及，因此，我们需要创建简单易懂且易于使用的聊天机器人文档。

因此，我们需要让现有的聊天机器人文档更易于访问和浏览，为每个受支持的框架提供统一的分步说明和丰富的示例，以便提供全面而清晰的文档。此外，还应对其进行整理，以清除冗余和难以理解的信息。

该项目的目标是缩小知识差距，鼓励经验不足的新开发者为热情的观众带来尖端技术的益处。为此，我们为聊天机器人构建者提供了在 Rocket.Chat 中开发自己的聊天机器人的简化体验。此目标旨在让 Rocket.Chat 成为这些开发者首选的开源平台，无论最终的聊天机器人部署目标如何，他们都可以在此平台上创新、构建和测试聊天机器人想法。

项目问题

下面列出了与聊天机器人文档相关的最关键问题：

  1. 有关聊天机器人的一般信息不直观且不友好
  2. 与聊天机器人架构相关的散乱且冗余的部分
  3. “入门”指南说明零散，没有单一可靠来源
  4. 缺少说明或说明过于详细
  5. 隐式且含糊不清的聊天机器人 SDK 文档

项目提案

根据项目目标和上述问题，下面列出了建议的增强功能：

  1. 更新了聊天机器人文档。为了让初始介绍顺畅且一致，应更新以下文档，从简单逐步过渡到更复杂：

    • 聊天机器人概览：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 周：与导师一起探讨聊天机器人的全新愿景。根据愿景，为新的聊天机器人首页创建更新后的内容。

第 2 周：复习“聊天机器人概览”“架构”“环境配置”页面

第 3 周 - 定义应转移到主要文档的子项目（聊天机器人 GitHub 代码库）列表。 - 定义聊天机器人网站在转移后应如何运作。 - 定义用于整理这些代码库中信息的模板。 - 为移交准备主要文档

第 4 周：转移 bBot 代码库。根据定义的模板整理信息

第 5 周：转移 Hubot 代码库。根据定义的模板整理信息

第 6 周：转移 Botkit 代码库。根据定义的模板整理信息

第 7 周：转移 Rasa 代码库。根据定义的模板整理信息

第 8 周：转移 BotPress 代码库。根据定义的模板整理信息

第 9 周：转移所有聊天机器人子项目后，最终确定主要文档结构和页面

第 10 周：检查 JSDoc 配置。定义存储 JSDoc 工件的目录。开始记录驱动程序方法

第 11 周：完成驱动程序方法的记录

第 12 周：评估结果

里程碑的详细细分

申请审核期

该阶段的前半部分将专门用于查看社区渠道和源代码，并与专门负责该项目的人员联系。

第二部分则是了解总体的投稿文化，了解投稿指南和最佳做法。这将是首次贡献内容，以了解该流程的运作方式。

社区互动

本次我们将深入探讨文档库及其路线图。基于这些信息，您可以找出可以改进的弱点（例如，不完整或缺失的部分）。创建拉取请求（如有可能）来填补空白。

第 1 周 - 第 2 周

第一周将专门用于与导师沟通，以便就聊天机器人文档的新愿景达成一致。这些信息将纳入修订后的文档中，旨在让读者大致了解聊天机器人及其工作原理。

第二周将根据愿景为新的聊天机器人首页创建内容，并修改“聊天机器人概览”“架构”“环境配置”页面。

经过修改的文档将更明确地针对以下各方： - 希望创建自己的聊天机器人的新开发者 - 希望使用免费且易用的平台设计/编码/测试聊天机器人或将现有聊天机器人适应该平台的专业 [聊天机器人] 开发者 - 希望为 Rocket.Chat 创建聊天机器人且有自己的框架偏好的专业聊天机器人开发者

工作范围如下：

  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/creating-bot-users/#talk-to-your-bot)

  2. 修改了“聊天机器人概览”页面的部分和字词，以便遵循 DRY 原则，清晰描述聊天机器人生态系统和功能。

    修改了有关“底层”信息的部分和字词：

    • 从技术角度来看，聊天机器人是什么
    • 它包含哪些组成部分
    • 这些组件如何协同工作

  3. 撰写一份快速入门指南，说明创建聊天机器人所需执行的步骤（并提供“配置聊天机器人环境”链接作为进一步阅读）。本指南将位于“环境配置”页面下。

这样一来，开发者就能清晰地了解聊天机器人的性质以及聊天机器人能够执行哪些操作。从那时起，开发者便可以创建自己的第一个聊天机器人了。

交付成果：经过修改的简单易懂的入门指南，其中包含有关聊天机器人生态系统和架构的信息。

第 3 - 9 周

第 3 到第 9 周将专门用于统一 GitHub 代码库中的所有聊天机器人文档，并将这些文档转移到主要文档 (https://rocket.chat/docs/bots/)。这些活动可以分为多次迭代：

  1. 定义

    定义应迁移到主要文档的聊天机器人子项目列表。定义聊天机器人网站在转移后应如何运作（例如，有些聊天机器人 [http://bbot.chat] 除了 GitHub 之外，还有单独的网站提供文档）。

  2. 模板

    定义并创建模板（一种方式），以整理第 1 步中定义的聊天机器人子项目中的信息。此模板可能如下所示：

    a. 克隆代码库

    b. 安装依赖项

    c. 配置聊天机器人

    d. 运行聊天机器人

    e. 高级配置

    f. 后续步骤

    对于包含一些非琐碎输出的命令（例如“运行聊天机器人”），应使用 Term Sheets 工具 (https://neatsoftware.github.io/term-sheets/) 实时演示该输出。

    此外，为了让初始的“快速入门”阶段（步骤 a - d）更加清晰，我们还会将所有步骤合并到一个直播演示中。

    为了让新手能够放心地使用，避免潜在的失败情况，应在 Playground 环境（使用 Glitch，作为 Rocket Chat 生态系统的一部分）中提供代码示例，让新手可以与内置“示例代码”的机器人聊天。

  3. 准备工作

    准备转移的主要文件。这包括创建适当的文件夹和页面结构，以及根据该结构调整目录。

    最终的结构可能如下所示：

    • 聊天机器人
      • 聊天机器人架构
      • 创建聊天机器人用户
      • 配置聊天机器人环境
      • 运行聊天机器人
        • bBot 聊天机器人
        • Hubot 聊天机器人
        • Botkit Bot
        • Rasa 聊天机器人
        • Botpress Bot

  4. 迁移

    将定义的聊天机器人子项目逐个迁移到主要文档。每个聊天机器人文档将都有单独的页面，其中包含当前版本（例如运行 bBot）等子部分。

    • 运行聊天机器人
      • bBot 聊天机器人
      • Hubot 聊天机器人
      • Botkit Bot
      • Rasa 聊天机器人
      • Botpress 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 以开发者自述文件的形式分散文档。这些自述文件完全没有结构，包含过时的新手入门信息，或者包含过多信息（有时会出现三重冗余，例如关于如何使用 Docker 运行聊天机器人的 hubot [https://github.com/RocketChat/hubot-rocketchat]），以及包含环境变量的表格。

开发者（作为新手）对这些方面的细节感到困惑。因此，开发者将无法仅通过几个终端命令启动和运行聊天机器人。

转移和优化完成后，GitHub 中现有的聊天机器人代码库将包含引用主要文档的自述文件。

这将带来以下好处： - 统一的结构让开发者更轻松地开始使用新聊天机器人 - 聊天机器人文档的单一可信来源 - 借助统一的结构，更轻松地查找有关任何聊天机器人的重要信息

交付物：将项目整理到一个位置（主文档），简单易懂，说明如何创建、配置和运行 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 周

完成工作并进行最终确认。验收检查。