Rocket.Chat 项目

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

项目摘要

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

Project description

项目摘要

聊天机器人是当今技术的最前沿。聊天机器人和聊天机器人的总体增长率非常高，以及语音识别和自动化技术的飞速发展，这使得创建易于掌握和使用的聊天机器人文档需要满足。

完整清晰的文档就变得愈发重要，因此现有聊天机器人文档需要更易于访问和导航，应为每个支持的框架提供统一的分步说明，并提供大量示例。此外，还应将网站整理得井井有条，去掉多余的和难以理解的信息。

该项目的目标是弥合知识差距，并鼓励经验不足的新开发者将先进技术的优势带给广大受众。这可以通过为机器人构建者提供在 Rocket.Chat 中开发自己的机器人的简化体验来实现。此目标旨在使 Rocket.Chat 成为这些开发者的首选开源平台，供这些开发者用于创新、创建和测试其聊天机器人创意，而无论 BOT 部署的最终目标是什么。

项目问题

下面列出了与漫游器文档相关的最严重问题：

  1. 关于漫游器的一般信息不直观且不友好
  2. 与聊天机器人架构相关的散乱部分和冗余部分
  3. “使用入门”指南说明内容条理清晰，没有单一的可信来源
  4. 缺乏说明或说明级别过于详细
  5. 隐式和模糊的 Bot 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 周

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

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

修订后的文档将更明确地着眼： - 希望创建自己的聊天机器人的新开发者 - 希望使用易于使用的免费平台设计/编写/测试机器人的专业 [bot] 开发者，或者希望根据现有机器人适应该平台而设计/编码/测试其机器人 - 具有框架偏好且希望为 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. 定义

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

  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 文件没有任何结构、包含有关如何开始使用的过时信息，或者包含过多的信息（有时会有三重冗余，例如关于如何使用 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 周

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