Rocket.Chat project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
Rocket.Chat
Technical writer:
Mister Gold
Project name:
The Bot Docs
Project length:
Standard length (3 months)

Project description

PROJECT SUMMARY

Chat Bots are on the cutting edge of today’s technology. Huge overall growth rates in chat software and bots along with speech recognition and automation on the rise dictate the need for creating bot documentation that is easy to grasp and use.

Having comprehensive and clear documentation becomes even more crucial, so the existing bots documentation needs to be made easier to access and navigate, should provide unified step-by-step instructions for each supported framework, and extensive examples. Also it should be tidied up to get rid of redundant and hard to understand information.

The project’s goal is to bridge the knowledge gap and encourage new, less experienced developers to bring the benefits of cutting-edge technology to an excited audience. This can be done by providing bot builders with a streamlined experience in developing their own bots in Rocket.Chat. This goal aims at making Rocket.Chat the preferred open source platform for these developers to innovate, create, and test their chatbot ideas on - regardless of the ultimate BOT deployment target.

Project Issues

The following is a list of the most crucial issues related to bots documentation:

  1. Non-intuitive and unfriendly general information about bots
  2. Scattered and redundant sections related to bots architecture
  3. Disorganized pieces of “getting started” guide instructions with no single source of truth
  4. Lack of instructions or an excessive level of instruction details
  5. Implicit and vague Bot SDK documentation

PROJECT PROPOSAL

According to the project’s goal, and the issues outlined above, the following is a list of the proposed enhancements:

  1. Update bot docs. To make the initial introduction smooth and consistent, the following documents should be updated with a gradual switch from simple to more complex:

    • Bots Overview: https://rocket.chat/docs/bots/
    • Bots Architecture: https://rocket.chat/docs/bots/bots-architecture/
    • Configuring bot environments: https://rocket.chat/docs/bots/configure-bot-environment/
    • Bots Home Page: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. Organize and unify bots installation documentation. All the sub-projects should have a unified set of instructions on how to clone a bot repository and install required dependencies, how to get started quickly, how to work with a bot after the first launch, and how to deploy it.

  3. Revise Rocket.Chat JS SDK documentation presentation. SDK documentation should be generated programmatically from the source code using specialized tools. This improvement will bring readability and eliminate the need to update the document on Github manually each time a method (or something inside it) changes.

TIMELINE

Application Review Period: Get familiar with the community and people to work with. Learn community contribution guides and best practices. Make the first contributions.

Community Bonding: Explore the community. Inspect the current state of bot documentation. Identify weak points.

Week 1: Align with mentors on the new vision of Bots. Create an updated content for the new Bots Home Page according to the vision.

Week 2: Revise Bots Overview, Architecture, Configuration of Environment pages

Week 3 - Define a list of sub-projects (bot github repos) that should be transferred into the main documentation. - Define how bot websites should work after the transfer. - Define a template that will be used to organize info within these repos. - Prepare the main documentation for the transfer

Week 4: Transfer bBot repo. Organize information according to the defined template

Week 5: Transfer Hubot repo. Organize information according to the defined template

Week 6: Transfer Botkit repo. Organize information according to the defined template

Week 7: Transfer Rasa repo. Organize information according to the defined template

Week 8: Transfer BotPress repo. Organize information according to the defined template

Week 9: Finalization of the main documentation structure and pages after transferring all the bot sub-projects

Week 10: Check JSDoc configuration. Define a place to store JSDoc artifacts. Start documenting driver methods

Week 11: Finish documenting driver methods

Week 12: Evaluate results

DETAILED BREAKDOWN OF MILESTONES

APPLICATION REVIEW PERIOD

The first part of the period will be dedicated to checking community channels and source code and contacting people who are dedicated to the project.

The second part of the period will be devoted to checking the contribution culture in general, examining contribution guides and best practices. This will be the time for first contributions to see how the flow works.

COMMUNITY BONDING

This time will be devoted to a deeper examination of the documentation repository along with its roadmap. Based on that information, it will be possible to identify weak points (e.g. incomplete or missing parts) that can be improved. Create pull requests (where possible) to fill the gaps.

WEEK 1 - WEEK 2

The first week will be devoted to communication with mentors in order to align on the new vision for Bots documentation. This information will be a part of the revised documents aimed at giving readers a general overview of what a bot is and its working principles.

The second week will be about creating content for the new Bots Home Page according to the vision and revising Bots Overview, Architecture, Configuration of Environment pages.

The revised documents will have a clearer focus at: - New developers who want to create their own bot - Professional [bot] developers who want to design/code/test their bots using a free and easy-to-use platform or adapt to their existing bots to that platform - Professional bot developers with their framework preferences who want to create bots for Rocket.Chat

The scope of work will be the following:

  1. Remove redundant sections. For example, the following sections share overlapping information:
    • How do bots send and receive messages? In Bots Overview (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Message Streams in Bots Architecture (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Talk to your bot in Creating Bot Users (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot)

  2. Revise sections and phrases of the Bots Overview page to make it clearly describe bots ecosystem and functionality following DRY principle.

    Revise sections and phrases about the information ""under the hood"":

    • What a bot is from a technical perspective
    • What components it consists of
    • How these components work together

  3. Write a quick start guide describing the steps required to create a bot (with a link to the ""Configuring bot environments"" as further reading). This guide will be placed under the Configuration of Environment page.

In this way, a developer will have a clear vision of bots nature, and what bots are capable of doing. From that point, a developer will be able to create their first bot.

Deliverables: Revised, easy to follow introduction guides with the information about bots ecosystem and architecture.

WEEK 3 - 9

Weeks 3 to 9 will be dedicated to the unification of all bot docs across github repositories and transferring these docs to the main documentation (https://rocket.chat/docs/bots/). These activities can be divided into several iterations:

  1. Definition

    Defining a list of bot sub-projects that should be migrated to the main documentation. Define how bot websites should work after the transfer (some bots, bbot, for example (http://bbot.chat)) have separate sites with documentation in addition to github).

  2. Template

    Defining and creating a template (a way) to organize information within the bot sub-projects defined on the 1st step. This template may look as follows:

    a. Clone a repo

    b. Install dependencies

    c. Configure a bot

    d. Run a bot

    e. Advanced configuration

    f. Further steps

    The commands that include some non-trivial output (like ""run a bot"") should be accompanied by live presentations of that output using Term Sheets tool (https://neatsoftware.github.io/term-sheets/).

    Furthermore, to make the initial ""quick start"" stage (steps a - d) clearer, all the steps will also be combined in one live presentation.

    To make newcomers feel safe from potential failures, examples of code should be provided with the playground environment (using Glitch, as a part of the Rocket Chat eco-system) where newcomers can chat with bots that have the ""example code"" under-the-hood.

  3. Preparation

    Preparing the main documentation for a transfer. This includes creation of the proper folder and page structure, as well as adjusting table of contents according to that structure.

    The final structure may look as follows:

    • Bots
      • Bots Architecture
      • Create Bot Users
      • Configure Bot Environment
      • Run Bots
        • bBot Bot
        • Hubot Bot
        • Botkit Bot
        • Rasa Bot
        • Botpress Bot

  4. Migration

    Migrating the defined bot sub-projects to the main documentation one-by-one. Each piece of bot documentation will have a separate page with sub-sections like the current version (e.g. running a bBot).

    • Run Bots
      • bBot Bot
      • Hubot Bot
      • Botkit Bot
      • Rasa Bot
      • Botpress Bot

  5. Organization

    There will be several activities:

    1. Organizing the information from each bot github repo according to the template defined on the 2nd step.
    2. Moving common components (e.g. environmental variables) that are related to all bot sub-projects one level up in the hierarchy of the main documentation and link bot sub-projects to these components
    3. Creating an example of “hello world” bot for each supported framework. This example will be used as a “getting started” bot for the Rocket.Chat.

Why is this important? All 8 sub-projects supported by Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy have scattered docs in the form of developers READMEs. These READMEs have no structure at all, contain outdated information on how to get started, or contain too much information (sometimes with triple redundancy, like hubot (https://github.com/RocketChat/hubot-rocketchat) about how to run a bot using Docker), as well as the table containing environmental variables.

These aspects confuse a developer (as a newcomer) with the tremendous level of detail. As a result, the developer will fail to get a bot up and running with just a few terminal commands.

After transfer and optimization are completed, the existing bot repositories in github will have README files that refer to the main documentation.

This will provide the following benefits: - A unified structure that makes it easier for developers to get started with new bots - Single source of truth for bots documentation - Easier to find the necessary piece of information about any bot thanks to the unified structure

Deliverables: organized under the single place (main documentation) easy-to-follow instructions on how to create, configure and run bots supported by Rocket.Chat.

WEEK 10

This week will be dedicated to configuring JSDoc (https://devdocs.io/jsdoc/) to maximize the value of inline comments. This includes:

  1. Ensuring that JSDoc is configured properly to parse comments for driver methods (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
  2. Install postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) to make the resulting HTML output more explicit and developer-friendly
  3. Defining the place where JSDoc documentation artifacts will be published
  4. Describing all the functions (in dist/lib/driver.js) file related to the driver methods. This includes:
    • Adding/editing descriptions of methods
    • Adding/editing descriptions of method parameters
    • Adding/editing examples of method requests, if applicable
    • Adding/editing examples of method responses, if applicable

Inline documentation is easier to write and maintain from the developer’s perspective and its auto-generation mechanism allows you to get rid of static documentation hosted on GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) that must be updated separately on each change in SDK methods.

WEEK 11

This week will be fully devoted to the finalization of describing driver methods. Once completed, the descriptions will be tested for accuracy and consistency and then the new documentation will be published to the world.

WEEK 12

Finalization of completed work. Acceptance checks.