Rocket.Chat 项目

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

项目摘要

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

Project description

项目摘要

聊天机器人是当今尖端技术。聊天机器人和聊天机器人的总体增长率非常高，而且语音识别和自动化技术也在不断增长，这使得创建易于掌握和使用的聊天机器人文档变得很需要。

提供全面清晰的文档变得愈加重要，因此现有的机器人文档需要更易于访问和导航，并为每个支持的框架提供统一的分步说明，以及大量示例。此外，还应整理信息，以删除冗余和难以理解的信息。

该项目的目标是消除知识缺口，并鼓励经验不足的新开发者将先进技术的优势带给感兴趣的受众群体。这可以为机器人构建者提供流畅的体验，让他们能够在 Rocket.Chat 中开发自己的机器人。此目标旨在将 Rocket.Chat 打造成首选开源平台，供这些开发者进行创新、创建和测试其聊天机器人想法，无论 BOT 的最终部署目标如何。

项目问题

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

  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 周

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

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

修订后的文档将更加明确地关注以下内容： - 希望创建自己的聊天机器人的新开发者 - 希望使用免费且易用的平台设计/编码/测试机器人的专业 [聊天机器人] 开发者，或根据该平台调整现有机器人 - 具有框架偏好并希望为 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. 定义

    定义应迁移到主文档的聊天机器人子项目列表。指定在转移后聊天机器人网站应如何运作（某些漫游器、Bbot 例如 (http://bbot.chat)）除了 GitHub 之外还有单独的网站，并提供相关文档。

  2. 模板

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

    a. 克隆代码库

    b. 安装依赖项

    c. 配置聊天机器人

    d. 运行聊天机器人

    e. 高级配置

    f. 后续步骤

    如果命令中包含一些重要的输出内容（例如“运行聊天机器人”），则应使用术语表工具 (https://neatsoftware.github.io/term-sheets/)，附上相关输出的实时演示。

    此外，为了让初始的“快速入门”阶段（步骤 a - d）更清晰，所有步骤也将合并到一个现场演示中。

    为了让新玩家不会遇到潜在故障，应该在 Playground 环境中提供代码示例（使用 Glitch，作为 Rocket Chat 生态系统的一部分），让新玩家能够与在后台与具有“示例代码”的机器人聊天。

  3. 准备

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

    最终结构可能如下所示：

    • 聊天机器人
      • 聊天机器人架构
      • 创建聊天机器人用户
      • 配置聊天机器人环境
      • 运行聊天机器人
        • bBot 聊天机器人
        • Hubot 机器人
        • Botkit 聊天机器人
        • 罗莎·博特 (Rasa Bot)
        • Botpress 聊天机器人

  4. 迁移

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

    • 运行聊天机器人
      • bBot 聊天机器人
      • Hubot 机器人
      • Botkit 聊天机器人
      • 罗莎·博特 (Rasa Bot)
      • Botpress 聊天机器人

  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]），以及包含环境变量的表格。

这些方面让开发者（作为新手）与非常详细的信息感到困惑。因此，开发者只用几个终端命令就无法启动并运行聊天机器人。

转移和优化完成后，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 周

已完成的工作定稿。验收检查。