Projeto Rocket.Chat

Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.

Resumo do projeto

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

Project description

RESUMO DO PROJETO

Os chatbots estão na vanguarda da tecnologia atual. As enormes taxas gerais de crescimento em software de chat e bots, além do reconhecimento de fala e da automação em ascensão, determinam a necessidade de criar documentação de bot fácil de entender e usar.

Ter uma documentação abrangente e clara é ainda mais importante. Por isso, a documentação dos bots precisa ser mais fácil de acessar e navegar, além de fornecer instruções detalhadas unificadas para cada framework compatível e exemplos detalhados. Além disso, você deve organizar tudo 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 para um público animado. Isso é feito fornecendo aos criadores de bots uma experiência simplificada para o desenvolvimento dos próprios bots no Rocket.Chat. O objetivo é tornar o Rocket.Chat a plataforma de código aberto preferida para que esses desenvolvedores inovem, criem e testem ideias de chatbots, seja qual for o destino de implantação de BOT.

Problemas do projeto

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

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

PROPOSTA DO PROJETO

De acordo com o objetivo do projeto e os problemas descritos acima, veja a seguir uma lista das melhorias propostas:

  1. Atualizar 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 complexa:

    • Visão geral dos bots: https://rocket.chat/docs/bots/
    • Arquitetura de bots: https://rocket.chat/docs/bots/bots-architecture/
    • Como configurar ambientes de bot: 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 bots 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 para JavaScript. A documentação do SDK precisa ser gerada de forma programática a partir do código-fonte com ferramentas especializadas. Essa melhoria vai proporcionar mais legibilidade e eliminar a necessidade de atualizar manualmente o documento no GitHub sempre que um método ou algo dentro dele for alterado.

Minuto a minuto

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

Vínculo comunitário: explore a comunidade. Inspecione o estado atual da documentação do bot. Identifique pontos fracos.

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

Semana 2: revisão das páginas de ambiente, arquitetura e configuração dos bots

Semana 3: defina uma lista de subprojetos (repositórios do GitHub de bots) 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: transferência do repositório bBot Organizar as informações de acordo com o modelo definido

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

Semana 6: transferência do repositório do Botkit Organizar as informações de acordo com o modelo definido

Semana 7: transferência do repositório Rasa Organizar as informações de acordo com o modelo definido

Semana 8: transferência do repositório BotPress Organizar as informações de acordo com o modelo definido

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

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

Semana 11: conclusão da documentação dos métodos do driver

Semana 12: avalie os resultados

ANÁLISE DETALHADA DOS MARCOS

PERÍODO DE ANÁLISE DA INSCRIÇÃO

A primeira parte do período será dedicada a verificar os canais da comunidade e o código-fonte, além de entrar em contato com pessoas dedicadas ao projeto.

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

VINCULAÇÃO DA COMUNIDADE

Este tempo será dedicado a um exame mais detalhado do repositório de documentação, junto com o roteiro dele. 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 os mentores, com o objetivo de alinhar a documentação sobre a nova visão para bots. Essas informações farão parte dos documentos revisados, que têm como objetivo dar aos leitores uma visão geral do que é um bot e seus princípios de funcionamento.

A segunda semana será sobre a criação de conteúdo para a nova página inicial dos bots de acordo com a visão e a revisão das páginas de visão geral, arquitetura e configuração de bots.

Os documentos revisados terão um foco mais claro em: - Novos desenvolvedores que querem criar o próprio bot - Desenvolvedores profissionais [bot] que querem projetar/codificar/testar seus bots usando uma plataforma sem custo financeiro e fácil de usar ou se adaptar aos bots existentes nessa plataforma - Desenvolvedores de bots profissionais com preferências de estrutura que querem criar bots para o Rocket.Chat

O escopo do trabalho será o seguinte:

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

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

    Revise seções e frases sobre as informações ""em segundo plano"":

    • O que é um bot do ponto de vista técnico
    • Quais componentes são compostos
    • Como esses componentes funcionam juntos

  3. Escreva um guia de início rápido descrevendo as etapas necessárias para criar um bot (com um link para "Como configurar ambientes de bot" como uma leitura adicional). Este guia será colocado na página Configuração do ambiente.

Dessa forma, o desenvolvedor terá uma visão clara da natureza dos bots e do que eles são capazes de fazer. Depois disso, o desenvolvedor pode criar o primeiro bot.

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

SEMANA 3 - 9

As semanas três a nove serão dedicadas à unificação de todos os documentos de 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 bot que devem ser migrados para a documentação principal. Defina como os sites de bots vão funcionar após a transferência (alguns bots, bbot, por exemplo, http://bbot.chat) têm sites separados com documentação, além do github.

  2. Modelo

    Definir e criar um modelo (uma forma) de organizar informações nos subprojetos de bot definidos na primeira etapa. Esse 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 por 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 a d), todas as etapas serão combinadas em uma única apresentação ao vivo.

    Para que os novos usuários se sintam seguros contra possíveis falhas, é preciso apresentar exemplos de código no ambiente do playground (usando o Glitch, como parte do ecossistema Rocket Chat), onde os novos usuários podem conversar com bots que têm o ""exemplo de código"" internamente.

  3. Preparação

    Como preparar a documentação principal para uma transferência. Isso inclui a criação da estrutura de páginas e pastas adequada, bem como o ajuste do índice de acordo com essa estrutura.

    A estrutura final pode ficar assim:

    • Bots
      • Arquitetura de bots
      • Criar usuários de bot
      • Configurar ambiente de bot
      • Executar bots
        • Bot bbot
        • Robô
        • Botkit
        • Bot Rasa
        • Botpress

  4. Migração

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

    • Executar bots
      • Bot bbot
      • Robô
      • Botkit
      • Bot Rasa
      • Botpress

  5. Organização

    Várias atividades serão realizadas:

    1. Organizar as informações de cada repositório do GitHub de bots de acordo com o modelo definido na segunda etapa.
    2. mover componentes comuns (por exemplo, variáveis de ambiente) relacionados a todos os subprojetos de bot para 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 introdução para o Rocket.Chat.

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

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

Depois que a transferência e a otimização forem concluídas, os repositórios de bots no GitHub terão arquivos README que se referem à documentação principal.

Com isso, você tem os seguintes benefícios: - Uma estrutura unificada que facilita para os desenvolvedores começarem a usar novos bots - Fonte única de verdade para documentação de bots - Mais facilidade para encontrar as informações necessárias sobre qualquer bot graças à estrutura unificada

Entregas: organizadas em um só local (documentação principal) e fáceis de seguir sobre como criar, configurar e executar bots compatíveis com o Rocket.Chat.

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. Garantia de que o JSDoc está 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 resultante mais explícita e fácil de usar para o desenvolvedor
  3. Definir o local onde os artefatos da 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:
    • Adicionar/editar descrições de métodos
    • Adicionar/editar descrições de parâmetros de método
    • Adição/edição de exemplos de solicitações de método, se aplicável
    • Adicionar/editar exemplos de respostas do método, se aplicável

A documentação inline é mais fácil de escrever e manter da perspectiva do desenvolvedor, e seu 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 a cada mudança nos métodos do SDK.

SEMANA 11

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

SEMANA 12

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