Esta página contém os detalhes de um projeto de redação 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:
- 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 de hoje. As enormes taxas de crescimento geral em software de chat e bots, além do reconhecimento de fala e da automação em alta, ditam a necessidade de criar uma documentação de bot que seja fácil de entender e usar.
Ter uma documentação abrangente e clara se torna 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 abrangentes. Além disso, ele deve ser organizado 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 animado. Isso pode ser feito fornecendo aos criadores de bots uma experiência simplificada para desenvolver seus próprios bots no Rocket.Chat. O objetivo do objetivo é tornar o Rocket.Chat a plataforma de código aberto preferencial para que esses desenvolvedores inovem, criem e testem as ideias de chatbots, independentemente do destino final de implantação de BOT.
Problemas do projeto
Confira a seguir uma lista dos problemas mais importantes relacionados à documentação dos bots:
- Informações gerais não intuitivas e hostis sobre bots
- Seções dispersas e redundantes relacionadas à arquitetura de bots
- Partes desorganizadas das instruções do guia de iniciação sem uma única fonte de informações
- Falta de instruções ou um nível excessivo de detalhes das instruções
- 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 de melhorias propostas:
Atualização dos documentos do bot. Para que a introdução inicial seja tranquila e consistente, vamos atualizar os documentos a seguir 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 bot: https://rocket.chat/docs/bots/configure-bot-environment/
- Página inicial de bots: https://github.com/RocketChat/rocketchat.github.io/pull/ (em inglês)
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.
Revise a apresentação da documentação do SDK do Rocket.Chat para JS. A documentação do SDK precisa ser gerada de forma programática a partir do código-fonte com ferramentas especializadas. Essa melhoria vai facilitar a leitura 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 guias de contribuição da comunidade e práticas recomendadas. Faça as primeiras contribuições.
Vínculo da comunidade: explore a comunidade. Inspecione o estado atual da documentação do bot. Identifique os pontos fracos.
Semana 1: alinhamento com mentores sobre a nova visão dos bots Cria um conteúdo atualizado para a nova página inicial dos bots de acordo com a visão.
Semana 2: revisar as páginas "Visão geral dos bots", "Arquitetura" e "Configuração do ambiente"
Semana 3 - Defina uma lista de subprojetos (repositórios de bots do GitHub) 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 informações nesses repositórios. - Preparar a documentação principal para a transferência
Semana 4: transferir o repositório 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: transferência do 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: transferência do repositório 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 de bot
Semana 10: verificar 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 dos drivers
Semana 12: avaliar os resultados
ANÁLISE DETALHADA DOS MARCOS
PERÍODO DE ANÁLISE DA INSCRIÇÃO
A primeira parte do período será dedicada à verificação dos canais da comunidade e do 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.
VÍNCULO COM A COMUNIDADE
Este tempo será dedicado a uma análise mais profunda do repositório de documentação, juntamente com seu 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 farão parte dos documentos revisados que visam 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 do ambiente.
Os documentos revisados terão um foco mais claro em: - Novos desenvolvedores que queiram criar seus próprios bots - Desenvolvedores profissionais [bot] que queiram projetar/codificar/testar bots usando uma plataforma sem custo financeiro e fácil de usar ou se adaptar aos bots existentes nela - Desenvolvedores de bots profissionais com suas preferências de framework que querem criar bots para o Rocket.Chat
O escopo do trabalho será o seguinte:
- Remova as seções redundantes.
Por exemplo, as seções a seguir compartilham informações sobrepostas:
- 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)
- Streams 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 bot (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot)
Revise as seções e frases da página "Visão geral dos bots" para descrever com clareza o ecossistema e a funcionalidade dos 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
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 leitura adicional). Este guia será inserido na página Configuração do ambiente.
Dessa forma, um desenvolvedor terá uma visão clara da natureza dos bots e do que eles são capazes de fazer. A partir desse ponto, o desenvolvedor poderá 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 3 a 9 serão dedicadas à unificação de todos os documentos de bots 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:
Definição
Definir uma lista de subprojetos bot que devem ser migrados para a documentação principal. Defina como os sites de bots devem funcionar após a transferência (alguns bots, por exemplo, bbot, por exemplo, http://bbot.chat)) têm sites separados com documentação e github.
Modelo
Definir e criar um modelo (uma forma) para organizar informações nos subprojetos 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 resultados incomuns (como "executar um bot") precisam ser acompanhados por apresentações ao vivo desses resultados usando a ferramenta Term Sheets (https://neatsoftware.github.io/term-sheets/).
Além disso, para deixar o estágio de ""início rápido"" inicial (etapas a - d) mais claro, 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 precisam ser fornecidos no ambiente de playground (usando o Glitch, como parte do ecossistema Rocket Chat), onde os novos podem conversar com bots que têm o ""exemplo de código"" internamente.
preparação
Como preparar a documentação principal para uma transferência. Isso inclui a criação da estrutura adequada de pastas e páginas, bem como o ajuste do sumário de acordo com essa estrutura.
A estrutura final pode ter a seguinte aparência:
- Bots
- Arquitetura dos bots
- Criar usuários de bot
- Configurar ambiente de bot
- Executar bots
- Bot bBot
- Bot hubot
- Bot do Botkit
- Bot Rasa
- Botpress
- Bots
Migração
Migrar os subprojetos 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, execução de um bBot).
- Executar bots
- Bot bBot
- Bot hubot
- Bot do Botkit
- Bot Rasa
- Botpress
- Executar bots
Organização
Serão realizadas várias atividades:
- Organizar as informações de cada repositório do GitHub do bot de acordo com o modelo definido na segunda etapa.
- Mover componentes comuns (por exemplo, variáveis de ambiente) relacionados a todos os subprojetos bot um nível acima na hierarquia da documentação principal e vincular subprojetos de bot a esses componentes
- Criação de um exemplo de bot “hello world” para cada framework compatível. Este exemplo será usado como um bot de "como começar" para o Rocket.Chat.
Por que isso é importante? Os oito subprojetos apoiados pelo Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy têm documentos espalhados no formato READMEs de desenvolvedores. Esses READMEs não têm estrutura, contêm informações desatualizadas sobre como começar ou contêm muita informação (à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 com 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 atuais no GitHub terão arquivos README que se referem à documentação principal.
Estes são os benefícios: - Uma estrutura unificada que ajuda os desenvolvedores a começar a usar os 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 único local (documentação principal) de instruções 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:
- 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)
- 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 os desenvolvedores.
- Definir o local em que os artefatos da documentação do JSDoc serão publicados
- Descrição de todas as funções (no arquivo dist/lib/driver.js) relacionadas aos métodos de driver. Isso inclui:
- Adição/edição de 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
- Adição/edição de exemplos de respostas dos métodos, se aplicável
A documentação inline é mais fácil de escrever e manter do ponto de vista 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 em cada alteração nos métodos do SDK.
SEMANA 11
Esta semana será dedicada à finalização da descrição dos métodos dos motoristas. 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 publicamente.
SEMANA 12
Conclusão do trabalho concluído. Verificações de aceitação.