Proyecto Rocket.Chat

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.

Resumen del proyecto

Organización de código abierto:

Rocket.Chat

Escritor técnico:

Señor Oro

Nombre del proyecto:

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 en software de chat y bots junto con el reconocimiento de voz y la automatización en aumento dictan la necesidad de crear documentación sobre bots que sea fácil de comprender y usar.

Tener documentación completa y clara se vuelve aún más importante, por lo que es necesario facilitar el acceso y la navegación de la documentación de bots existente, debería proporcionar instrucciones paso a paso unificadas para cada framework compatible y extensos 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, puedes brindarles a los desarrolladores de bots una experiencia optimizada en el desarrollo de sus propios bots en Rocket.Chat. El objetivo es convertir a Rocket.Chat en 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 bots que no es intuitiva y difícil de usar
2. Secciones dispersas y redundantes relacionadas con la arquitectura de los bots
3. Piezas desorganizadas de instrucciones de la guía de “introducción” sin una única fuente de verdad.
4. Falta de instrucciones o un nivel excesivo de detalles sobre las instrucciones
5. Documentación implícita y imprecisa del SDK de bot

PROPUESTA DE PROYECTO

De acuerdo con el objetivo del proyecto y los problemas descritos anteriormente, a continuación se presenta 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 simple a más complejo:

   • 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 los 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 y cómo 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 JS. La documentación del SDK debe generarse de manera programática a partir del código fuente con herramientas especializadas. Esta mejora facilitará la lectura y eliminará la necesidad de actualizar el documento en GitHub de forma manual cada vez que cambie un método (o algún elemento dentro de él).

Cronología

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

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

Semana 1: Alinéate con los mentores con respecto a la nueva visión de los bots. Cree un contenido actualizado para la nueva página principal de bots de acuerdo con la 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 bots de GitHub) que se deben transferir a la documentación principal. - Define cómo deberían funcionar los sitios web de bots después de la transferencia. - Define una plantilla que se usará para organizar la información 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 recursos Hubot. Organizar la información según la plantilla definida

Semana 6: Transfiere el 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 de BotPress. Organizar la información según la plantilla definida

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

Semana 10: Verifica la configuración de JSDoc. Define un lugar para almacenar artefactos 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

DESCRIPCIÓN DETALLADA DE LOS HITOS

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

La primera parte del período estará dedicada a verificar 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 comprobar 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 período se dedicará a un análisis más profundo del repositorio de documentación, junto con su hoja de ruta. A partir de esa información, será posible identificar los puntos débiles (por ejemplo, partes incompletas o faltantes) que se pueden mejorar. Crear 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 mentores para acordar la nueva visión de la documentación de los bots. Esta información forma parte de los documentos revisados 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 tratará sobre la creación de contenido para la nueva página principal de los bots en función de 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 se enfocarán más en lo siguiente: - Desarrolladores nuevos que quieran crear su propio bot - Desarrolladores [bots] profesionales que deseen diseñar, codificar y 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 deseen 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)
   • Habla con tu bot en Cómo crear usuarios de bots (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 describir claramente el ecosistema y la funcionalidad de los bots de acuerdo con el principio DRY.

   Revisa las secciones y frases sobre la información "de manera interna":

   • Qué es un bot desde una perspectiva técnica
   • Qué componentes contiene
   • Cómo estos componentes funcionan juntos

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 bots" 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 estos son capaces de hacer. A partir de ese momento, un desarrollador podrá crear su primer bot.

Ítems: 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

Las semanas 3 a 9 se dedicarán a la unificación de todos los documentos de bots en los 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. Cómo ejecutar 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-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 ante posibles fallas, se deben proporcionar ejemplos de código en el entorno de zona de pruebas (mediante Glitch, como parte del ecosistema de Rocket Chat), donde los usuarios nuevos pueden chatear con bots que tienen el “código de ejemplo” de forma interna.

3. Preparación

   Prepara la documentación principal para una transferencia. Esto incluye crear la estructura adecuada de carpetas y páginas, así como ajustar el índice de acuerdo con esa estructura.

   La estructura final puede ser la siguiente:

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

4. Migración

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

   • Ejecutar bots
     • bBot bot
     • Bot de hubot
     • Botkit
     • Bot de Rasa
     • Botpress

5. Organización

   Habrá varias actividades:

   1. Organizar la información de cada repositorio de GitHub de un bot según la plantilla definida en el segundo paso
   2. Mover los 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 los subproyectos del bot a estos componentes
   3. Crear un ejemplo de bot “Hello World” para cada framework compatible Este ejemplo se usará como el bot de "introducción" de Rocket.Chat.

¿Por qué es importante? Los 8 subproyectos compatibles con Rocket.Chat: alexa, existet, 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 estructura, contienen información desactualizada sobre cómo comenzar o contienen demasiada información (a veces, con triple redundancia, como existet (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) por su increíble nivel de detalle. Como resultado, el desarrollador no podrá poner en marcha un bot con solo algunos comandos de 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 - Una estructura unificada para encontrar la información necesaria sobre cualquier bot

Entregas: Se organizan en un único lugar (documentación principal) con instrucciones fáciles de seguir sobre cómo crear, configurar y ejecutar bots 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. 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 se dedicará por completo a la finalización de la descripción de los métodos de los conductores. Una vez completadas, se probará la precisión y coherencia de las descripciones y, luego, la nueva documentación se publicará para el mundo.

SEMANA 12

Finalización del trabajo terminado Verificaciones de aceptación