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:
- Cloud Native Computing Foundation (CNCF)
- Escritor técnico:
- Shriti
- Nombre del proyecto:
- Mejorar la documentación de SMI y las mallas de servicios relacionadas
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
El objetivo principal de la tecnología de la malla de servicios es proporcionar valor a la creciente cantidad de servicios mediante el manejo de todas tus necesidades de seguridad, administración y supervisión. La interfaz de malla de servicios (SMI) define un conjunto de APIs para los casos de uso más comunes de la malla de servicios (política de tráfico, telemetría y cambios) y habilita la compatibilidad entre las mallas de servicios, que son capas de infraestructura dedicadas para controlar la comunicación de servicio a servicio en un entorno de microservicios. La estandarización de estas interfaces proporcionará una experiencia mejorada para el usuario final y, por lo tanto, es un objetivo futuro para las SMI y las mallas de servicios relacionadas.
Estado actual:
Guías del usuario: SMI es un proyecto de zona de pruebas relativamente nuevo que se donó a CNCF en abril de 2020. Como resultado, al proyecto le falta documentación para el usuario final. Meshery es un plano de administración de servicios con comparativas de rendimiento para todo tipo de servicios que facilitan la adopción, la configuración, la operación y la administración del rendimiento de diferentes mallas de servicios, y incorpora la recopilación y visualización de métricas de aplicaciones que se ejecutan sobre cualquier malla de servicios. Por lo tanto, me gustaría comenzar con una guía para Meshery, que servirá como punto de partida para toda la comunidad de usuarios de SMI.
Instructivos para usuarios: Entre las plataformas de SMI existentes, la aplicación de ejemplo, Learn Layer5, actualmente sirve como dispositivo de aprendizaje para SMI y como aplicación de ejemplo para realizar la validación de especificaciones de SMI.Sin embargo, por lo demás, los proyectos de SMI carecen por completo de instructivos para usuarios finales, lo que es un grave obstáculo debido a la naturaleza altamente técnica de los proyectos. Meshery es la aplicación perfecta para mostrar los beneficios y el uso de SMI y las mallas de servicios relacionadas, por lo que la usaré como herramienta base para mostrar las funciones de SMI.
Documentación de la API: por el momento, no existe. SMI y varios proyectos relacionados tienen sus extremos de API definidos en una plataforma. Por ejemplo, Meshery tiene sus extremos definidos en server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), pero no están bien comentados ni documentados de forma externa. Esto se puede resolver con documentación significativa de las APIs y se puede mejorar agregando formas para que los usuarios prueben sus extremos y obtengan una vista previa de sus funciones.
Análisis:
Los tutoriales del usuario se crean para permitir que el usuario participe y ejecute una prueba del Software. Deben ser interactivas y estéticamente atractivas para mantener la atención del usuario y, lo que es más importante, fáciles de usar.
Sin embargo, para redactar u alojar Guías de usuario, se recomienda usar un formato más maduro, ya que estas suelen servir como guía de referencia o como un lugar para solucionar rápidamente los problemas. En lugar de ser interactivos, deben estar bien estructurados y centrarse en mejorar la claridad, la coherencia y el buen flujo de usuarios.
Una posible solución a esto sería crear instructivos para usuarios independientes con Codelabs de Google y una guía del usuario independiente con la ayuda de Jekyll. Finalmente, integrarlos junto con la documentación de la API para brindar una experiencia completa a los usuarios finales y a los futuros colaboradores.
Público objetivo: Los proyectos de SMI proporcionan prácticas operativas y de implementación, entornos de aprendizaje y comparativas de rendimiento a todos los proyectos en ellos. Se adapta tanto a personas como a organizaciones.
Guías de usuario: Segmentaré la app para usuarios principiantes, sin suponer que tienen conocimientos de TI previos por parte de los usuarios. Objetivo: Usuarios principiantes Motivo: Se usa principalmente como una amplia guía de referencia que se deberá actualizar con el tiempo. Esto incluirá explicaciones detalladas y sugerencias útiles a fin de garantizar que el usuario tenga toda la información que necesita para configurar una malla de servicios y trabajar con ella. La Guía será más atractiva y fácil de usar agregando videos, imágenes, capturas de pantalla y GIF, cuando sea necesario.
Instructivos para usuarios: Objetivo: Usuarios principiantes Motivo: El objetivo será hacer que los instructivos sean atractivos y estéticos para captar la atención del usuario y permitir una ejecución de prueba del software sin problemas, lo que conducirá a una mejor comprensión de la interfaz de la malla de servicios.
Documentación del extremo de la API: Objetivo: Usuarios avanzados Motivo: Esta sección se centra en el uso de las funciones más complejas de la malla de servicios, cuyo interés principal es el de los usuarios avanzados con un nivel básico de conocimiento de TI. Los usuarios avanzados buscarán instructivos concisos que también se pueden utilizar como guías de referencia, si es necesario. La documentación del extremo debe escribirse de una manera para que sea fácil de actualizar sin comprometer su exactitud o coherencia. Preferentemente, este proceso debería ser automatizado.
Recursos: Instructivos de usuario: Codelab de Google Developers; se usa para crear instructivos interactivos y completos para usuarios finales. Beneficios: - Puede producir instructivos para la zona de pruebas. - Tiene un enfoque práctico. - Escrito con Documentos de Google y compatible con texto Markdown. - Se puede supervisar con Google Analytics - Es fácil observar el tráfico de usuarios. - Fácil de usar. Produce tutoriales estéticamente atractivos que permiten al usuario interactuar directamente con el software sin ninguna inversión directa.
Los Codelabs de Google se pueden mejorar e implementar fácilmente con el proyecto CLaaT (Codelabs como una cosa). Este es un programa que ofrece una herramienta de línea de comandos que se usa para convertir los instructivos escritos en Documentos de Google con Markdown en formato de codelabs (HTML).
Guías de usuario: Jekyll: la documentación existente de mallaery.io, que puedes encontrar aquí, está alojada en Jekyll y utiliza el tema Docsy Jekyll. Utiliza Markdown, liquid, HTML y CSS con el objetivo de producir sitios web estáticos listos para alojar y ejecutar en un entorno de desarrollo de Ruby. Beneficios: - Puede alojar sitios directamente desde los repositorios de GitHub. - Este proyecto cuenta con una buena compatibilidad y una comunidad muy activa - Se pueden agregar fácilmente guías de usuario y mejoras a la documentación existente de SMI y Meshery, sin tener que preocuparse por migrar a otra plataforma.
Documentación de la API: Swagger (alternativamente, Swaggo) se usará para crear la documentación de la API de SMI y Meshery. Es una solución elegante para escribir documentos de API. Beneficios: - Documentación del diseño de tu API: Garantiza que tu documentación se mantenga actualizada a medida que tu API evoluciona. - Documentación de tu diseño de API: Se puede generar automáticamente a partir de las definiciones de API. - Mantener varias versiones de la documentación - Diseños de API personalizados
Objetivos del proyecto: - Usar los codelabs de Google Developers a fin de crear instructivos interactivos para usuarios finales para SMI y mallas de servicios relacionadas con Meshery como herramienta - Crear una guía del usuario final con Jekyll para las mallas de servicios - Usar Swagger a fin de generar documentación de extremos de API para SMI. - Hacer que el proyecto sea impulsado por la comunidad, de modo que los usuarios o desarrolladores futuros y actuales puedan continuar ampliando su proyecto fácilmente bajo la orientación y moderación de la comunidad de SMI.
Cronograma: El cronograma propuesto se encuentra en el siguiente vínculo: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
Estructura: La estructura propuesta para la guía del usuario se puede encontrar aquí: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
¿Por qué este proyecto? La comunidad de la malla de servicios se está expandiendo a un ritmo vertiginoso, gracias a su reciente integración como proyecto de zona de pruebas en CNCF. Sin embargo, el proyecto está presenciando una gran escasez de documentación, tanto para los usuarios finales como para los desarrolladores. En el pasado, jugué con varias mallas de servicio, como linkerD con la aplicación EmojiVoto, Istio con su aplicación Bookinfo y Consul de Hashicorp. También probé la división del tráfico de SMI y ya implementé varias reglas de validación en la configuración de la malla de servicios. El proceso de aprendizaje es fascinante, pero altamente técnico, y puede ser desalentador para los usuarios nuevos y los desarrolladores que buscan dar sus primeros pasos en la comunidad de la malla de servicios o utilizar mallas de servicios para sus propios proyectos personales o profesionales. Quiero cerrar esta brecha, que solo se puede hacer con instructivos y guías eficientes y bien documentados.