Proyecto Rocket.Chat

Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.

Resumen del proyecto

Organización de código abierto:
Rocket.Chat
Redactor técnico:
Mister Gold
Nombre del proyecto:
Los documentos de bot
Duración del proyecto:
Duración estándar (3 meses)

Project description

RESUMEN DEL PROYECTO

Los chat bots están a la vanguardia de la tecnología actual. Las enormes tasas de crecimiento general de software de chat y bots, junto con el reconocimiento de voz y la automatización en aumento, determinan la necesidad de crear documentación sobre bots que sea fácil de comprender y usar.

Tener documentación completa y clara resulta aún más importante, por lo que es necesario facilitar el acceso y la navegación a la documentación de los bots existentes, además de proporcionar instrucciones unificadas paso a paso para cada framework admitido, además de numerosos ejemplos. También se debe ordenar para eliminar la información redundante y difícil de entender.

El objetivo del proyecto es reducir la brecha de conocimiento y alentar a los desarrolladores nuevos y menos experimentados a llevar los beneficios de la tecnología de vanguardia a un público entusiasmado. Para ello, se debe proporcionar una experiencia optimizada a los desarrolladores de bots en el desarrollo de sus propios bots en Rocket.Chat. Este objetivo es hacer de Rocket.Chat la plataforma de código abierto preferida para que estos desarrolladores innoven, creen y prueben sus ideas de chatbots, independientemente del objetivo final de implementación del BOT.

Problemas del proyecto

La siguiente es una lista de los problemas más importantes relacionados con la documentación de bots:

  1. Información general sobre los bots que no es intuitiva y que no es fácil de usar
  2. Secciones dispersas y redundantes relacionadas con la arquitectura de bots
  3. Piezas desorganizadas de instrucciones de guía para “comenzar” sin una única fuente de verdad
  4. Falta de instrucciones o un nivel excesivo de detalles sobre la instrucción
  5. Documentación implícita y imprecisa del SDK de Bot

PROPUESTA DEL PROYECTO

Según el objetivo del proyecto y los problemas descritos anteriormente, la siguiente es una lista de las mejoras propuestas:

  1. Actualiza la documentación del bot. Para que la introducción inicial sea fluida y coherente, los siguientes documentos deben actualizarse con un cambio gradual de simples a más complejos:

    • Descripción general de los bots: https://rocket.chat/docs/bots/
    • Arquitectura de bots: https://rocket.chat/docs/bots/bots-architecture/
    • Configuración de entornos de bots: https://rocket.chat/docs/bots/configure-bot-environment/
    • Página principal de bots: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. Organizar y unificar la documentación de instalación de bots Todos los subproyectos deben tener un conjunto unificado de instrucciones sobre cómo clonar un repositorio de bots e instalar las dependencias requeridas, cómo comenzar rápidamente, cómo trabajar con un bot después del primer lanzamiento y cómo implementarlo.

  3. Revisa la presentación de la documentación del SDK de Rocket.Chat para JS. La documentación del SDK se debe generar de manera programática a partir del código fuente con herramientas especializadas. Esta mejora facilitará la lectura y eliminará la necesidad de actualizar manualmente el documento en GitHub cada vez que cambie un método (o algo dentro de él).

Cronología

Período de revisión de postulaciones: Familiarízate con la comunidad y las personas con las que trabajarás. Conoce las guías de contribución de la comunidad y las prácticas recomendadas. Realiza las primeras contribuciones.

Vinculación comunitaria: explora la comunidad. Inspecciona el estado actual de la documentación del bot. Identificar los puntos débiles.

Semana 1: Alinéate con los mentores sobre la nueva visión de los bots. Crea un contenido actualizado para la nueva página principal de bots según tu visión.

Semana 2: Revisa las páginas Descripción general de los bots, Arquitectura y Configuración del entorno

Semana 3 - Define una lista de subproyectos (repositorios de GitHub del bot) que se deben transferir a la documentación principal. - Defina cómo deben funcionar los sitios web de bots después de la transferencia. - Define una plantilla que se usará para organizar la información dentro de estos repositorios. - Preparar la documentación principal para la transferencia

Semana 4: Transfiere el repositorio de bBot. Organizar la información según la plantilla definida

Semana 5: Transfiere el repositorio de Hubot. Organizar la información según la plantilla definida

Semana 6: Transferencia del repositorio de Botkit Organizar la información según la plantilla definida

Semana 7: Transfiere el repositorio de Rasa. Organizar la información según la plantilla definida

Semana 8: Transfiere el repositorio BotPress. Organizar la información según la plantilla definida

Semana 9: Finalización de la estructura de documentación principal y las páginas después de transferir todos los subproyectos del bot

Semana 10: Verifica la configuración de JSDoc. Define un lugar para almacenar artefactos de JSDoc. Comienza a documentar los métodos del controlador

Semana 11: Termina de documentar los métodos del controlador

Semana 12: Evalúa los resultados

Desglose DETALLADO DE LOS HITOS

PERÍODO DE REVISIÓN DE LA POSTULACIÓN

La primera parte del período se dedicará a revisar los canales y el código fuente de la comunidad, y a contactar a las personas que se dedican al proyecto.

La segunda parte del período se dedicará a revisar la cultura de contribución en general y a examinar las guías de contribución y las prácticas recomendadas. Este será el momento de las primeras contribuciones para ver cómo funciona el flujo.

VÍNCULOS CON LA COMUNIDAD

Este tiempo se dedicará a un análisis más profundo del repositorio de documentación junto con su hoja de ruta. Con esa información, será posible identificar los puntos débiles (por ejemplo, partes incompletas o faltantes) que se pueden mejorar. Crea solicitudes de extracción (cuando sea posible) para llenar los vacíos.

SEMANA 1 - SEMANA 2

La primera semana se dedicará a la comunicación con los mentores para acordar la nueva visión de la documentación de los bots. Esta información formará parte de los documentos revisados que tienen como objetivo brindar a los lectores una descripción general de lo que es un bot y sus principios de funcionamiento.

La segunda semana tratará sobre la creación de contenido para la nueva página principal de bots según la visión y la revisión de las páginas Descripción general, Arquitectura y Configuración del Entorno de los bots.

Los documentos revisados tendrán un enfoque más claro en lo siguiente: - Desarrolladores nuevos que desean crear su propio bot - Desarrolladores [bots] profesionales que desean diseñar, codificar o probar sus bots con una plataforma gratuita y fácil de usar, o adaptarse a sus bots existentes a esa plataforma - Desarrolladores de bots profesionales con sus preferencias de framework que desean crear bots para Rocket.Chat

El alcance del trabajo será el siguiente:

  1. Quita las secciones redundantes. Por ejemplo, las siguientes secciones comparten información superpuesta:
    • ¿Cómo envían y reciben mensajes los bots? Descripción general de los bots (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Flujos de mensajes en arquitectura de bots (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Cómo crear usuarios de bots (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot) conversa con tu bot

  2. Revisa las secciones y frases de la página Descripción general de bots para que describa con claridad el ecosistema y la funcionalidad de los bots según el principio DRY.

    Revisa las secciones y frases sobre la información "en profundidad":

    • Qué es un bot desde una perspectiva técnica
    • Componentes con los que cuenta
    • Cómo funcionan en conjunto estos componentes

  3. Escribe una guía de inicio rápido en la que se describan los pasos necesarios para crear un bot (con un vínculo a “Cómo configurar entornos de bot” como lectura adicional). Esta guía se colocará en la página Configuración del entorno.

De esta manera, el desarrollador tendrá una visión clara de la naturaleza de los bots y de lo que son capaces de hacer. A partir de ese momento, un desarrollador podrá crear su primer bot.

Entregas: Guías introductorias revisadas y fáciles de seguir que contienen información sobre el ecosistema y la arquitectura de los bots.

SEMANA 3 - 9

De la semana 3 a la 9, se dedicará a la unificación de todos los documentos de bots en repositorios de GitHub y a transferirlos a la documentación principal (https://rocket.chat/docs/bots/). Estas actividades se pueden dividir en varias iteraciones:

  1. Definición

    Definir una lista de subproyectos de bots que se deben migrar a la documentación principal Define cómo deben funcionar los sitios web de bots después de la transferencia (algunos bots, Bbot, por ejemplo, http://bbot.chat) tienen sitios separados con documentación, además de github.

  2. Template

    Definir y crear una plantilla (una forma) para organizar la información dentro de los subproyectos del bot definidos en el primer paso Esta plantilla puede tener el siguiente aspecto:

    a. Clonar un repositorio

    b. Instala dependencias

    c. Configura un bot

    d. Ejecuta un bot

    e. Configuración avanzada

    f. Pasos adicionales

    Los comandos que incluyen algún resultado no trivial (como “ejecutar un bot”) deben estar acompañados de presentaciones en vivo de ese resultado con la herramienta Hojas de términos (https://neatsoftware.github.io/term-sheets/).

    Además, para que la etapa inicial de "inicio rápido" (pasos a y d) sea más clara, todos los pasos también se combinarán en una presentación en vivo.

    Para que los principiantes se sientan seguros de posibles fallas, se deben proporcionar ejemplos de código en el entorno de zona de pruebas (con Glitch, como parte del ecosistema de Rocket Chat), donde pueden chatear con bots que tienen el "código de ejemplo" de forma interna.

  3. Preparación

    Preparación de la documentación principal para una transferencia. Esto incluye la creación de la estructura adecuada de carpetas y páginas, así como el ajuste del índice de acuerdo con dicha estructura.

    La estructura final puede ser la siguiente:

    • Bots
      • Arquitectura de bots
      • Crear usuarios bot
      • Configurar entorno del bot
      • Ejecutar bots
        • bBot bot
        • Hubo un bot
        • Botkit-Bot
        • bot de Rasa
        • Botpress

  4. Migración

    Migrar los subproyectos de bot definidos a la documentación principal, uno por uno. Cada documento de la documentación del bot tendrá una página independiente con subsecciones como la versión actual (p.ej., ejecutar un bBot).

    • Ejecutar bots
      • bBot bot
      • Hubo un bot
      • Botkit-Bot
      • bot de Rasa
      • Botpress

  5. Organización

    Habrá varias actividades:

    1. Organizar la información de cada repositorio de GitHub de bot según la plantilla definida en el segundo paso
    2. Mover componentes comunes (p.ej., variables de entorno) relacionados con todos los subproyectos de bots a un nivel superior en la jerarquía de la documentación principal y vincular subproyectos de bots a estos componentes
    3. Cómo crear un ejemplo de bot de “Hello World” para cada framework compatible Este ejemplo se usará como bot de introducción para Rocket.Chat.

¿Por qué es importante? Los 8 subproyectos compatibles con Rocket.Chat: alexa, tiempot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana y hubot-gitsy tienen documentos dispersos en forma de archivos README de los desarrolladores. Estos archivos README no tienen ninguna estructura, contienen información desactualizada sobre cómo comenzar o contienen demasiada información (a veces con triple redundancia, como hubot (https://github.com/RocketChat/hubot-rocketchat) sobre cómo ejecutar un bot con Docker), además de la tabla que contiene variables de entorno.

Estos aspectos confunden a los desarrolladores (como principiante) con el increíble nivel de detalle. Como resultado, el desarrollador no podrá poner en marcha un bot con solo algunos comandos de la terminal.

Una vez completadas la transferencia y la optimización, los repositorios de bots existentes en GitHub tendrán archivos README que hacen referencia a la documentación principal.

Esto proporcionará los siguientes beneficios: - Una estructura unificada que facilita a los desarrolladores comenzar a usar bots nuevos - Una única fuente de información para la documentación de los bots - Es más fácil encontrar la información necesaria sobre cualquier bot gracias a la estructura unificada

Entregas: Se organizan en un único lugar (documentación principal) con instrucciones fáciles de seguir sobre cómo crear, configurar y ejecutar bots que son compatibles con Rocket.Chat.

SEMANA 10

Esta semana se dedicará a configurar JSDoc (https://devdocs.io/jsdoc/) para maximizar el valor de los comentarios intercalados. Esto incluye lo siguiente:

  1. Asegúrate de que JSDoc esté configurado correctamente para analizar comentarios de métodos de controlador (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods).
  2. Instala postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) para que el resultado del código HTML resultante sea más explícito y fácil de usar para los desarrolladores.
  3. Definir el lugar donde se publicarán los artefactos de documentación de JSDoc
  4. La descripción de todas las funciones (in dist/lib/driver.js) relacionadas con los métodos del controlador. Incluye lo siguiente:
    • Agregar o editar descripciones de métodos
    • Agregar o editar descripciones de parámetros de métodos
    • Agregar o editar ejemplos de solicitudes de métodos, si corresponde
    • Agregar o editar ejemplos de respuestas de métodos, si corresponde

La documentación intercalada es más fácil de escribir y mantener desde la perspectiva del desarrollador, y su mecanismo de generación automática te permite deshacerte de la documentación estática alojada en GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) que debe actualizarse por separado en cada cambio en los métodos del SDK.

SEMANA 11

Esta semana, estará completamente dedicada a la finalización de la descripción de los métodos de los controladores. Una vez completadas, se probará la precisión y coherencia de las descripciones y, luego, la nueva documentación se publicará para todo el mundo.

SEMANA 12

Finalización del trabajo completado. Verificaciones de aceptación.