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:
- Cloud Native Computing Foundation (CNCF)
- Redactor técnico:
- Shriti
- Nombre del proyecto:
- Mejora la documentación de SMI y las mallas de servicios relacionadas
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
La tecnología de malla de servicios tiene como objetivo principal proporcionar valor a la creciente cantidad de servicios, ya que controla todas tus necesidades de seguridad, administración y supervisión. La interfaz de Service Mesh (SMI) define un conjunto de APIs para los casos de uso más comunes de Service Mesh (política de tráfico, telemetría y cambio) y habilita la compatibilidad entre Service Mesh, 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 la SMI y las mallas de servicios relacionadas.
Estado actual:
Guías para el 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, configuración, operación y administración del rendimiento de diferentes mallas de servicios. Además, 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 el usuario: Entre las plataformas de SMI existentes, la aplicación de ejemplo, Learn Layer5, actualmente funciona como un dispositivo de aprendizaje para SMI y como la aplicación de ejemplo para realizar la validación de especificaciones de SMI.Sin embargo, los proyectos de SMI carecen por completo de instructivos para usuarios finales, lo que es un gran 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: No existe en este momento. 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 instructivos para el usuario se crean para permitir que el usuario participe y realice una prueba del software. Deben ser interactivos y atractivos a nivel estético para mantener la atención del usuario y, lo más importante, ser fáciles de usar.
Sin embargo, para redactar u alojar guías del usuario, se recomienda utilizar un formato más maduro, ya que las guías del usuario a menudo sirven como guía de referencia o como un lugar para obtener una solución rápida de los problemas. En lugar de ser interactivos, deben estar bien estructurados y enfocarse en mejorar la claridad, la coherencia y un buen flujo de usuarios.
Una posible solución a esto sería crear instructivos para usuarios independientes con Google Codelabs y una Guía del usuario independiente con la ayuda de Jekyll y, por último, integrarlos junto con la documentación de la API para brindar una experiencia integral al usuario final y a los futuros colaboradores.
Público objetivo: Los proyectos de SMI proporcionan prácticas de implementación y operativas, entornos de aprendizaje y comparativas de rendimiento a todos los proyectos que los conforman. Se adapta a personas y organizaciones.
Guías de usuario: Me orientaré a usuarios principiantes sin presunciones de que los usuarios tengan conocimientos de TI preexistentes. 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 para garantizar que el usuario tenga toda la información que necesita para configurar y trabajar con una malla de servicios. La guía se hará más atractiva y fácil de usar, ya que agregará videos, imágenes, capturas de pantalla y GIFs, cuando sea necesario.
Instructivos para el usuario: Segmentación: Usuarios principiantes Motivo: El objetivo será hacer que los instructivos sean atractivos y estéticamente atractivos para mantener la atención del usuario y permitir una prueba fluida del software, lo que llevará a una mejor comprensión de la interfaz de Service Mesh.
Documentación sobre los extremos 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, que están más orientadas a los usuarios avanzados con un nivel básico de conocimiento de TI. Los usuarios avanzados buscarán instructivos concisos que también se puedan usar como guías de referencia, si es necesario. La documentación del extremo debe escribirse de manera tal que sea fácil de actualizar sin comprometer su precisión o coherencia. Preferentemente, debería ser un proceso automatizado.
Recursos: Instructivos para el usuario: Codelab de Google Developers: Se usa para crear instructivos interactivos y completos para el usuario final. Beneficios: - Puede producir instructivos de zona de pruebas. - Tiene un enfoque práctico. - Escribiste con Documentos de Google y admite texto Markdown. - Se pueden supervisar con Google Analytics. Es fácil observar el tráfico de los usuarios. - Fácil de usar. Produce instructivos estéticamente agradables que permiten al usuario interactuar directamente con el software sin ninguna inversión directa.
Los codelabs de Google se pueden mejorar y, además, implementar fácilmente con el proyecto CLaaT (Codelabs as a Thing). Este es un programa que ofrece una herramienta de línea de comandos que se usa para convertir instructivos escritos en Documentos de Google con Markdown en el formato de codelabs (HTML).
Guías para el usuario: Jekyll: La documentación existente de meshery.io, que se encuentra aquí, se aloja en Jekyll y usa el tema Docsy Jekyll. Usa Markdown, Liquid, HTML y CSS para producir sitios web estáticos listos para alojar y se ejecuta en un entorno de desarrollo de Ruby. Beneficios: - Puedes alojar sitios directamente desde los repositorios de GitHub. - Este es un proyecto bien respaldado con una comunidad muy activa. - Las guías para el usuario y las mejoras se pueden agregar a la documentación existente de SMI y Meshery sin tener que preocuparse por migrar a otra plataforma.
Documentación de la API: Se usará Swagger (o Swaggo) 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 de tu diseño de API: Garantiza que tu documentación se mantenga actualizada a medida que tu API evoluciona. - Documentación de tu diseño de API: puede generarse automáticamente a partir de definiciones de API. - Mantener varias versiones de la documentación - Diseños de API personalizados
Objetivos del proyecto: - Usa Codelabs de Google Developer para crear instructivos interactivos para usuarios finales de SMI y mallas de servicios relacionadas con Meshery como herramienta. - Crear una guía para el usuario final con Jekyll para las mallas de servicios - Usa Swagger para generar documentación de extremos de API para SMI. - Haz que el proyecto sea impulsado por la comunidad para que los usuarios o desarrolladores actuales y futuros puedan seguir agregándolo fácilmente bajo la guía y moderación de la comunidad de SMI.
Cronograma: Puedes encontrar el cronograma propuesto aquí: 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 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 tiene una gran escasez de documentación, tanto para los usuarios finales como para los desarrolladores. En el pasado, probé varias mallas de servicios, como linkerD con la app de EmojiVoto, Istio con su aplicación de bookinfo y Consul de Hashicorp. También probé la división del tráfico de SMI y, además, implementé varias reglas de validación en mi configuración de malla de servicios. El proceso de aprendizaje es fascinante, pero muy técnico y puede ser un obstáculo tanto para los usuarios nuevos como para 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. Me gustaría cerrar esta brecha, lo que solo se puede hacer con guías y instructivos eficientes y bien documentados.