Projeto Rocket.Chat

Esta página contém os detalhes de um projeto de escrita técnica aceito para o Temporada dos Documentos Google.

Resumo do projeto

Organização de código aberto:
Rocket.Chat
Redator técnico:
Mister Gold
Nome do projeto:
Documentação do bot
Duração do projeto:
Duração padrão (três meses)

Project description

RESUMO DO PROJETO

Os chatbots são a tecnologia mais avançada da atualidade. As taxas de crescimento gerais enormes em softwares de chat e bots, além do reconhecimento de voz e da automação em ascensão, determinam a necessidade de criar uma documentação de bot fácil de entender e usar.

Ter uma documentação abrangente e clara se torna ainda mais crucial. Portanto, a documentação dos bots precisa ser mais fácil de acessar e navegar, fornecer instruções detalhadas unificadas para cada framework compatível e exemplos extensos. Além disso, ela deve ser organizada para se livrar de informações redundantes e difíceis de entender.

O objetivo do projeto é preencher a lacuna de conhecimento e incentivar desenvolvedores novos e menos experientes a levar os benefícios da tecnologia de ponta a um público empolgado. Isso pode ser feito oferecendo aos criadores de bots uma experiência simplificada no desenvolvimento dos próprios bots no Rocket.Chat. O objetivo é fazer do Rocket.Chat a plataforma de código aberto preferencial para esses desenvolvedores inovarem, criarem e testarem ideias de chatbot, independentemente do objetivo de implantação do BOT final.

Problemas do projeto

Confira a seguir uma lista dos problemas mais importantes relacionados à documentação de bots:

  1. Informações gerais sobre bots que não são intuitivas e são hostis
  2. Seções dispersas e redundantes relacionadas à arquitetura de bots
  3. Peças desorganizadas das instruções de “Primeiros passos” sem uma única fonte de verdade
  4. Falta de instruções ou um nível excessivo de detalhes de instruções
  5. Documentação implícita e vaga do SDK do Bot

PROPOSTA DE PROJETO

De acordo com a meta do projeto e os problemas descritos acima, confira a seguir uma lista das melhorias propostas:

  1. Atualize os documentos do bot. Para que a introdução inicial seja tranquila e consistente, os documentos a seguir precisam ser atualizados com uma mudança gradual de simples para mais complexo:

    • Visão geral dos bots: https://rocket.chat/docs/bots/
    • Arquitetura de bots: https://rocket.chat/docs/bots/bots-architecture/
    • Como configurar ambientes de bots: https://rocket.chat/docs/bots/configure-bot-environment/
    • Página inicial de bots: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. Organize e unifique a documentação de instalação de bots. Todos os subprojetos precisam ter um conjunto unificado de instruções sobre como clonar um repositório de bot e instalar as dependências necessárias, como começar rapidamente, como trabalhar com um bot após o primeiro lançamento e como implantá-lo.

  3. Revise a apresentação da documentação do SDK do Rocket.Chat JS. A documentação do SDK precisa ser gerada de forma programática a partir do código-fonte usando ferramentas especializadas. Essa melhoria vai melhorar a legibilidade e eliminar a necessidade de atualizar o documento no GitHub manualmente sempre que um método (ou algo nele) mudar.

Minuto a minuto

Período de análise da inscrição: conheça a comunidade e as pessoas com quem você vai trabalhar. Conheça os guias e as práticas recomendadas de contribuição para a comunidade. Faça as primeiras contribuições.

Interação com a comunidade: explore a comunidade. Inspecione o estado atual da documentação do bot. Identifique os pontos fracos.

Semana 1: alinhar com os mentores a nova visão dos bots. Criar um conteúdo atualizado para a nova página inicial de bots de acordo com a visão.

Semana 2: revisar as páginas "Visão geral", "Arquitetura" e "Configuração de bots" das páginas do ambiente

Semana 3: Defina uma lista de subprojetos (repositórios do github do bot) que precisam ser transferidos para a documentação principal. - Definir como os sites de bots devem funcionar após a transferência. - Definir um modelo que será usado para organizar as informações nesses repositórios. - Preparar a documentação principal para a transferência

Semana 4: transferir o repositório do bBot. Organizar informações de acordo com o modelo definido

Semana 5: transferir o repositório do Hubot. Organizar informações de acordo com o modelo definido

Semana 6: transferir o repositório do Botkit. Organizar informações de acordo com o modelo definido

Semana 7: transferir o repositório Rasa. Organizar informações de acordo com o modelo definido

Semana 8: transferir o repositório do BotPress Organizar informações de acordo com o modelo definido

Semana 9: finalização da estrutura e das páginas da documentação principal após a transferência de todos os subprojetos do bot

Semana 10: verificar a configuração do JSDoc. Defina um local para armazenar artefatos do JSDoc. Comece a documentar os métodos do driver

Semana 11: concluir a documentação dos métodos do driver

Semana 12: avaliar os resultados

DETALHAMENTO DOS MARCOS

PERÍODO DE ANÁLISE DAS INSCRIÇÕES

A primeira parte do período será dedicada à verificação dos canais da comunidade e do código-fonte e ao contato com pessoas dedicadas ao projeto.

A segunda parte do período será dedicada à verificação da cultura de contribuições em geral, examinando os guias de contribuição e as práticas recomendadas. Esse será o momento das primeiras contribuições para ver como o fluxo funciona.

Vínculos com a comunidade

Desta vez, vamos nos aprofundar no repositório de documentação e no roteiro. Com base nessas informações, será possível identificar pontos fracos (por exemplo, partes incompletas ou ausentes) que podem ser melhorados. Crie solicitações de envio (quando possível) para preencher as lacunas.

SEMANA 1 - SEMANA 2

A primeira semana será dedicada à comunicação com mentores para alinhar a nova visão da documentação de bots. Essas informações vão fazer parte dos documentos revisados para dar aos leitores uma visão geral do que é um bot e como ele funciona.

Na segunda semana, vamos criar conteúdo para a nova página inicial de bots de acordo com a visão e revisar as páginas "Visão geral dos bots", "Arquitetura" e "Configuração do ambiente".

Os documentos revisados terão um foco mais claro em: - Novos desenvolvedores que querem criar seus próprios bots - Desenvolvedores profissionais de bots que querem projetar/codificar/testar os bots usando uma plataforma sem custo financeiro e fácil de usar ou adaptar os bots existentes a essa plataforma - Desenvolvedores profissionais de bots com preferências de framework que querem criar bots para o Rocket.Chat

O escopo do trabalho será o seguinte:

  1. Remova seções redundantes. Por exemplo, as seções a seguir compartilham informações sobrepostas:
    • Como os bots enviam e recebem mensagens? Visão geral sobre bots (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Fluxos de mensagens na arquitetura de bots (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Converse com seu bot em Como criar usuários de bots (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot)

  2. Revise as seções e frases da página "Visão geral de bots" para descrever claramente o ecossistema e a funcionalidade dos bots seguindo o princípio DRY.

    Revise as seções e frases sobre as informações "por trás dos bastidores":

    • O que é um bot do ponto de vista técnico
    • Quais componentes ele tem
    • Como esses componentes funcionam juntos

  3. Escreva um guia de início rápido que descreva as etapas necessárias para criar um bot (com um link para a página "Configurar ambientes de bot" como leitura complementar). Esse guia será colocado na página "Configuração do ambiente".

Dessa forma, os desenvolvedores terão uma visão clara da natureza dos bots e do que eles são capazes de fazer. A partir desse ponto, um desenvolvedor poderá criar o primeiro bot.

Entregas: guias de introdução revisados e fáceis de seguir com informações sobre o ecossistema e a arquitetura de bots.

SEMANA 3 a 9

As semanas 3 a 9 serão dedicadas à unificação de todos os documentos do bot nos repositórios do GitHub e à transferência desses documentos para a documentação principal (https://rocket.chat/docs/bots/). Essas atividades podem ser divididas em várias iterações:

  1. Definição

    Definir uma lista de subprojetos de bots que precisam ser migrados para a documentação principal. Defina como os sites de bots vão funcionar após a transferência. Alguns bots, como o bbot (http://bbot.chat), têm sites separados com documentação, além do GitHub.

  2. Modelo

    Definir e criar um modelo (uma maneira) para organizar informações nos subprojetos do bot definidos na primeira etapa. O modelo pode ter a seguinte aparência:

    a. Clonar um repositório

    b. Instalar dependências

    c. Configurar um bot

    d. Executar um bot

    e. Configuração avançada

    f. Outras etapas

    Os comandos que incluem alguma saída não trivial (como ""executar um bot"") devem ser acompanhados de apresentações ao vivo dessa saída usando a ferramenta Term Sheets (https://neatsoftware.github.io/term-sheets/).

    Além disso, para tornar mais clara a etapa de ""início rápido"" (etapas a - d), todas as etapas também serão combinadas em uma apresentação ao vivo.

    Para que os novatos se sintam seguros contra possíveis falhas, exemplos de código devem ser fornecidos com o ambiente de playground (usando o Glitch, como parte do ecossistema do Rocket Chat), onde os novatos podem conversar com bots que têm o ""código de exemplo"" por trás.

  3. Preparação

    Preparar a documentação principal para uma transferência. Isso inclui a criação da pasta e da estrutura de páginas adequadas, além de ajustar o sumário de acordo com essa estrutura.

    A estrutura final pode ficar assim:

    • Bots
      • Arquitetura de bots
      • Criar usuários de bots
      • Configurar o ambiente do bot
      • Executar bots
        • Bot bBot
        • Hubot Bot
        • Bot Botkit
        • Rasa Bot
        • Bot Botpress

  4. Migração

    Migrar os subprojetos de bot definidos para a documentação principal, um por um. Cada documentação do bot terá uma página separada com subseções, como a versão atual (por exemplo, "Executar um bBot").

    • Executar bots
      • Bot bBot
      • Hubot Bot
      • Bot Botkit
      • Rasa Bot
      • Bot Botpress

  5. Organização

    Haverá várias atividades:

    1. Organizar as informações de cada repositório do bot no GitHub de acordo com o modelo definido na segunda etapa.
    2. Mover componentes comuns (por exemplo, variáveis ambientais) relacionados a todos os subprojetos de bot um nível acima na hierarquia da documentação principal e vincular subprojetos de bot a esses componentes
    3. Criar um exemplo de bot "hello world" para cada framework compatível. Este exemplo será usado como um bot de "primeiros passos" para o Rocket.Chat.

Por que isso é importante? Os oito subprojetos aceitos pelo Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana e hubot-gitsy têm documentos dispersos no formato README dos desenvolvedores. Esses READMEs não têm estrutura alguma, contêm informações desatualizadas sobre como começar ou contêm muitas informações (às vezes com redundância tripla, como o hubot (https://github.com/RocketChat/hubot-rocketchat) sobre como executar um bot usando o Docker), bem como a tabela que contém variáveis ambientais.

Esses aspectos confundem um desenvolvedor (como um novato) com o nível enorme de detalhes. Como resultado, o desenvolvedor não conseguirá colocar um bot em funcionamento com apenas alguns comandos de terminal.

Após a conclusão da transferência e da otimização, os repositórios de bots existentes no GitHub terão arquivos README que se referem à documentação principal.

Isso vai oferecer os seguintes benefícios: - Uma estrutura unificada que facilita a iniciação dos desenvolvedores com novos bots - Uma única fonte de verdade para a documentação de bots - É mais fácil encontrar as informações necessárias sobre qualquer bot graças à estrutura unificada

Entregas: instruções fáceis de seguir sobre como criar, configurar e executar bots com suporte do Rocket.Chat, organizadas em um único lugar (documentação principal).

SEMANA 10

Esta semana será dedicada à configuração do JSDoc (https://devdocs.io/jsdoc/) para maximizar o valor dos comentários inline. Isso inclui:

  1. Garantir que o JSDoc esteja configurado corretamente para analisar comentários de métodos de driver (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
  2. Instale o postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) para tornar a saída HTML mais explícita e amigável para desenvolvedores.
  3. Como definir o local em que os artefatos de documentação do JSDoc serão publicados
  4. Descrição de todas as funções (no arquivo dist/lib/driver.js) relacionadas aos métodos do driver. Isso inclui:
    • Como adicionar/editar descrições de métodos
    • Adicionar/editar descrições de parâmetros de método
    • Adicionar/editar exemplos de solicitações de método, se aplicável
    • Adicionar/editar exemplos de respostas de método, se aplicável

A documentação inline é mais fácil de escrever e manter do ponto de vista do desenvolvedor, e o mecanismo de geração automática permite que você se livre da documentação estática hospedada no GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods), que precisa ser atualizada separadamente em cada mudança nos métodos do SDK.

SEMANA 11

Esta semana será totalmente dedicada à finalização da descrição dos métodos de condutor. Depois de concluídas, as descrições serão testadas para verificar a precisão e a consistência, e a nova documentação será publicada.

SEMANA 12

Finalização do trabalho concluído. Verificações de aceitação.