Proyecto Rocket.Chat

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

Resumen del proyecto

Organización de código abierto:

Rocket.Chat

Redactor técnico:

Mister Gold

Nombre del proyecto:

Documentos de Bot

Duración del proyecto:

Duración estándar (3 meses)

Project description

RESUMEN DEL PROYECTO

Los chatbots están a la vanguardia de la tecnología actual. Los enormes porcentajes de crecimiento generales en el software de chat y los bots, junto con el reconocimiento de voz y la automatización en aumento, dictan la necesidad de crear documentación de bots que sea fácil de entender y usar.

Contar con documentación completa y clara se vuelve aún más crucial, por lo que se debe facilitar el acceso y la navegación de la documentación de bots existente, debe proporcionar instrucciones paso a paso unificadas para cada marco de trabajo compatible y ejemplos exhaustivos. Además, se debe ordenar para eliminar la información redundante y difícil de entender.

El objetivo del proyecto es reducir la brecha de conocimiento e incentivar a los desarrolladores nuevos y menos experimentados a llevar los beneficios de la tecnología de vanguardia a un público entusiasta. Para ello, se les proporciona a los creadores de bots una experiencia optimizada para desarrollar sus propios bots en Rocket.Chat. Este objetivo tiene como objetivo hacer que Rocket.Chat sea la plataforma de código abierto preferida en la 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 poco intuitiva y poco amigable sobre los bots
2. Secciones dispersas y redundantes relacionadas con la arquitectura de los bots
3. Instrucciones desorganizadas de la guía de “cómo comenzar” sin una fuente de información única
4. Falta de instrucciones o un nivel excesivo de detalles en las instrucciones
5. Documentación implícita y vaga 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 los documentos del bot. Para que la introducción inicial sea fluida y coherente, se deben actualizar los siguientes documentos con un cambio gradual de simple a más complejo:

   • Descripción general de los bots: https://rocket.chat/docs/bots/
   • Arquitectura de los 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. Organiza y unifica la documentación de instalación de los bots. Todos los subproyectos deben tener un conjunto unificado de instrucciones para clonar un repositorio de bots e instalar las dependencias necesarias, comenzar a usarlo rápidamente, trabajar con un bot después del primer lanzamiento y, también, 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 forma programática a partir del código fuente con herramientas especializadas. Esta mejora mejorará la legibilidad y eliminará la necesidad de actualizar el documento en GitHub de forma manual cada vez que cambie un método (o algo dentro de él).

Cronología

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

Vinculación con la comunidad: Explora la comunidad. Inspecciona el estado actual de la documentación de bots. Identifica los puntos débiles.

Semana 1: Alinear con los mentores la nueva visión de los bots Crea contenido actualizado para la nueva página principal de Bots según la visión.

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

Semana 3: Define una lista de subproyectos (repositorios de GitHub de bots) que se deben transferir a la documentación principal. - Define 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. - Prepara la documentación principal para la transferencia

Semana 4: Transferir el repo 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: Transferir el repositorio de Botkit Organizar la información según la plantilla definida

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

Semana 8: Transferir el repositorio de BotPress Organizar la información según la plantilla definida

Semana 9: Finalización de la estructura y las páginas de la documentación principal 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 verificar los canales de la comunidad y el código fuente, y a comunicarse con las personas que se dedican al proyecto.

La segunda parte del período se dedicará a comprobar la cultura de contribución en general, 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.

VINCULOS DE COMUNIDAD

Este tiempo se dedicará a un examen más profundo del repositorio de documentación junto con su plan de ruta. Con esa información, será posible identificar los puntos débiles (p.ej., partes incompletas o faltantes) que se pueden mejorar. Crear solicitudes de extracción (cuando sea posible) para completar los vacíos

SEMANA 1 - SEMANA 2

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

La segunda semana se dedicará a crear contenido para la nueva página principal de Bots según la visión y a revisar las páginas Descripción general de Bots, Arquitectura y Configuración del entorno.

Los documentos corregidos tendrán un enfoque más claro en lo siguiente: - Desarrolladores nuevos que quieran crear su propio bot - Desarrolladores profesionales [de bots] que quieran diseñar, codificar o probar sus bots con una plataforma gratuita y fácil de usar, o adaptar sus bots existentes a esa plataforma - Desarrolladores profesionales de bots con sus preferencias de framework que quieran 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 la arquitectura de bots (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
   • Habla con tu bot en Cómo crear usuarios de bot (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot).

2. Revisa las secciones y frases de la página Descripción general de los bots para que describan claramente el ecosistema y la funcionalidad de los bots siguiendo el principio DRY.

   Revisa las secciones y frases sobre la información ""detrás de escena"":

   • Qué es un bot desde una perspectiva técnica
   • De qué componentes consta
   • Cómo funcionan juntos 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 la sección ""Configurar entornos de bots"" como lectura complementaria). Esta guía se colocará en la página Configuración del entorno.

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

Entregables: Guías de introducción revisadas y fáciles de seguir con información sobre el ecosistema y la arquitectura de los bots.

SEMANAS 3 A 9

Las semanas 3 a 9 se dedicarán a unificar todos los documentos de los bots en los repositorios de GitHub y 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 los bots después de la transferencia (algunos bots, como bbot (http://bbot.chat), tienen sitios separados con documentación además de GitHub).

2. Plantilla

   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 verse de la siguiente manera:

   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 ir acompañados de presentaciones en vivo de ese resultado con la herramienta de hojas de términos (https://neatsoftware.github.io/term-sheets/).

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

   Para que los recién llegados se sientan seguros ante posibles fallas, se deben proporcionar ejemplos de código con el entorno de la zona de pruebas (con Glitch, como parte del ecosistema de Rocket Chat), en el que los recién llegados pueden chatear con bots que tienen el ""código de ejemplo"" en su interior.

3. Preparación

   Preparar la documentación principal para una transferencia Esto incluye la creación de la estructura de carpetas y páginas adecuadas, así como el ajuste del índice según esa estructura.

   La estructura final puede verse de la siguiente manera:

   • Bots
     • Arquitectura de bots
     • Crea usuarios de bot
     • Configura el entorno del bot
     • Ejecuta bots
       • Bot de bBot
       • Bot generado
       • Botkit de bots
       • Bot de Rasa
       • Botpress de bot

4. Migración

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

   • Bots de ejecución
     • Bot de bBot
     • Bot generado
     • Botkit de bots
     • Bot de Rasa
     • Bot de Botpress

5. Organización

   Habrá varias actividades:

   1. La organización de la información de cada repositorio de GitHub de bots según la plantilla definida en el segundo paso.
   2. Mover los componentes comunes (p.ej., variables ambientales) que se relacionan con todos los subproyectos de bot un nivel hacia arriba en la jerarquía de la documentación principal y vincular los subproyectos de bot a estos componentes
   3. Crear un ejemplo de bot de "Hello World" para cada framework compatible Este ejemplo se usará como bot de “primeros pasos” para Rocket.Chat.

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

Estos aspectos confunden a un desarrollador (como recién llegado) con el gran nivel de detalle. Como resultado, el desarrollador no podrá iniciar un bot y ponerlo en funcionamiento con solo unos pocos comandos de la terminal.

Una vez que se completen 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

Entregables: instrucciones fáciles de seguir para crear, configurar y ejecutar bots compatibles con Rocket.Chat, organizadas en un solo lugar (documentación principal).

SEMANA 10

Esta semana, dedicaremos la configuración de JSDoc (https://devdocs.io/jsdoc/) para maximizar el valor de los comentarios intercalados. Esto incluye lo siguiente:

1. Asegurarse de que JSDoc esté configurado correctamente para analizar comentarios para los métodos del 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 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 la documentación de JSDoc
4. Describe todas las funciones (en el archivo dist/lib/driver.js) relacionadas con los métodos del controlador. Incluye lo siguiente:
   • Agregar o editar descripciones de métodos
   • Cómo agregar o editar descripciones de los parámetros del método
   • 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 se debe actualizar por separado en cada cambio en los métodos del SDK.

SEMANA 11

Esta semana se dedicará por completo a finalizar la descripción de los métodos de los controladores. Una vez completadas, se probará la exactitud y la coherencia de las descripciones y, luego, se publicará la nueva documentación para todo el mundo.

SEMANA 12

Finalizar el trabajo terminado. Verificaciones de aceptación