De qué trata esta publicación

  • La necesidad de un nuevo stack tecnológico más eficiente
  • La arquitectura técnica detrás de la transformación de nuestra documentación
  • Mejoras clave en velocidad, capacidades de búsqueda y UX
  • Beneficios tanto para nuestro equipo de desarrollo como para los usuarios de Zammad

¡La documentación de Zammad ha recibido una actualización completa! La hemos renovado de forma integral, tanto visual como estructuralmente, para que le resulte más fácil trabajar con Zammad, ya sea desarrollador, administrador o usuario.

Imagen de la documentación antigua y nueva de Zammad

Explore the new Zammad Documentation

Por qué estamos reconstruyendo nuestra documentación

La documentación de Zammad ha sido durante mucho tiempo una piedra angular de nuestra misión de código abierto. Clara, bien estructurada y accesible al público, ayuda a los equipos a sacar más provecho de Zammad todos los días.

Durante mucho tiempo, hemos dependido de Sphinx, un generador de sitios estáticos basado en Python que usa reStructuredText para generar contenido bien estructurado en diferentes medios. Toda la documentación de Zammad estaba alojada en Read the Docs Community, un recurso fantástico y gratuito.

Esta configuración nos sirvió bien durante años, pero a medida que tanto Zammad como nuestra base de colaboradores crecieron, se hizo cada vez más evidente que nuestro stack basado en Python ya no estaba a la altura. Su popularidad disminuyó a medida que aumentaba su complejidad, y con ella el temido 'infierno de dependencias'. Mientras tanto, surgieron alternativas más modernas y fáciles de usar que prometían un mejor rendimiento con menos gastos de mantenimiento: exactamente lo que nuestra creciente comunidad necesitaba.

El renacimiento de la web estática

Durante la última década, los sitios web estáticos han experimentado un resurgimiento impresionante. Con el objetivo de entregar de manera eficiente contenido que rara vez se actualiza a una audiencia en constante crecimiento, entraron en escena multitud de generadores de sitios estáticos, rápidamente adoptados por sus bajos costos de alojamiento y tiempos de carga ultrarrápidos.

En este panorama en evolución, se ha formado un equilibrio natural: los sitios estáticos han demostrado ser la solución perfecta para casos de uso como manuales de software y documentación. Y, honestamente, es simplemente más agradable trabajar con ellos, gracias a lenguajes de marcado ligeros como Markdown, que ocupan el centro del escenario y despejan nuestra mente.

Adoptando un stack tecnológico moderno con Vue.js/Vite

Para nuestra reescritura del escritorio (Desktop Rewrite), elegimos un stack tecnológico moderno: el framework de Vue.js como base y Vite como herramienta de empaquetado rápida y eficiente. Naturalmente, tenía sentido buscar una solución de documentación dentro del mismo ecosistema, aprovechando al máximo la experiencia de nuestro equipo.

Ahí entra VitePress, una plataforma que prometía hacer justo lo que queríamos, así que le dimos una oportunidad. Desarrollada sobre el bien establecido VuePress, proporciona soporte integrado de Markdown y se beneficia de una sólida comunidad. Nos gustó especialmente el elegante tema predeterminado, que incluye los modos claro y oscuro, lo que garantiza una experiencia de lectura cómoda, ya sea a la luz del día o en un entorno con poca luz.

Imagen del stack tecnológico antiguo y nuevo para la documentación de Zammad

Estructura que se organiza sola

La estructura de un sitio web estático es su columna vertebral: garantiza una organización rápida y lógica y un acceso rápido a la información. Los sistemas de archivos planos (flat-file) son perfectos para esto: simplemente coloque un archivo en la carpeta correcta y listo. Aunque VitePress no incluye esta funcionalidad por defecto, se puede añadir fácilmente mediante un plugin de la comunidad. Esta elección arquitectónica ofrece múltiples beneficios.

La navegación principal se puede derivar automáticamente de la estructura, junto con las rutas que siguen un esquema de URL limpia.

La navegación secundaria se soporta de forma nativa y se basa en el contenido real de los archivos Markdown. Atrás quedaron los días en que se necesitaban directivas para las tablas de contenido, it just works™.

VitePress también admite frontmatter, el estándar de facto para los metadatos de Markdown. Con solo unas pocas claves especiales, es posible controlar no solo la apariencia de una página, sino también su posición y presentación en la navegación. Esto crea posibilidades emocionantes para futuras extensiones y mejora significativamente la usabilidad tanto para los colaboradores como para los lectores.

Una solución práctica para la documentación multilingüe

Hacer que nuestra documentación fuera multilingüe fue inicialmente un poco un dolor de cabeza. Si bien VitePress ofrece soporte nativo para múltiples idiomas, su implementación es, diciéndolo amablemente, un poco tosca. Todos los archivos Markdown traducidos deben estar presentes en la estructura correcta desde el principio, lo que no encajaba bien con nuestra plataforma de traducción impulsada por la comunidad basada en Weblate.

La solución llegó en forma de una pequeña pero potente utilidad de Perl llamada po4a. Aún podía basarse en las cadenas de origen en formato gettext, pero podía proporcionarnos un proceso previo a la compilación provisional y confiable que puede preparar todos los archivos que necesitamos.

Esto dio como resultado el cumplimiento de un requisito: solo se debía modificar el contenido de origen en inglés, el resto se traduciría automáticamente y se generaría antes de la compilación. La desventaja es que parte del código Markdown todavía logra filtrarse en nuestras fuentes de traducción, pero consideramos que era un compromiso aceptable.

Para usted como usuario, esto significa una calidad de traducción más coherente, más idiomas disponibles y una documentación accesible en todo el mundo.

Capturas de pantalla automatizadas: Documentación visual que nunca se vuelve obsoleta

La documentación de Zammad siempre ha sido rica en elementos visuales, combinando instrucciones de texto sin formato con animaciones y capturas de pantalla para ilustrar cada paso. Sin embargo, mantener estas imágenes era tedioso: incluso los cambios menores en la interfaz de usuario podían requerir actualizaciones en numerosas imágenes en todas nuestras guías.

Así que pensamos: ¿Por qué no automatizarlo? Dado que la aplicación Zammad ya se ejecuta como un stack de Docker Compose, podemos arrancar la última versión de la aplicación localmente en cualquier momento. Y debido a que este sistema se puede poblar determinísticamente con datos de muestra, todo lo que necesitábamos era una herramienta para generar automáticamente las capturas de pantalla requeridas.

Ahí es donde entró Cypress. Construida originalmente para pruebas automatizadas, esta plataforma ofrece un potente sistema de scripts para capturas de pantalla bajo demanda. Con unas pocas extensiones específicas de Zammad, creamos una configuración que simplemente ejecuta un script de prueba de extremo a extremo, et voilà, todas las imágenes necesarias se generan al instante.

El resultado transforma nuestro flujo de trabajo: no hay más actualizaciones manuales de capturas de pantalla individuales, ni archivos binarios que saturen el repositorio. Más importante aún, los usuarios siempre ven exactamente cómo es la versión actual de Zammad, eliminando la confusión causada por imágenes obsoletas.

Pipeline CI/CD: La pieza final para una documentación verdaderamente automatizada

Finalmente, para rematar todo, implementamos un pipeline CI/CD. Este proceso automatizado se encarga de varias tareas esenciales, asegurando que nuestra documentación esté siempre actualizada:

  • Clonar el repositorio de la documentación
  • Integrar las últimas traducciones de Weblate
  • Generar capturas de pantalla actualizadas
  • Compilar el sitio de la documentación estática

Para la implementación, descubrimos que el autoalojamiento (self-hosting) ofrece el mayor control a largo plazo. Sin embargo, esta configuración sigue siendo flexible, según las necesidades. Afortunadamente, hoy en día, hay muchas plataformas de alojamiento gratuito disponibles, incluidas GitHub, GitLab Pages y Cloudflare Pages.

Zammad Docs 2.0 – ¿Qué opina?

Estamos construyendo este nuevo sistema de documentación teniendo en mente a la comunidad, y eso lo incluye a usted. Es por eso que lo invitamos a explorar nuestra nueva documentación y experimentar la diferencia de primera mano. Si detecta problemas, tiene sugerencias o desea contribuir con nuevo contenido, lo animamos a involucrarse.

Puede abrir un issue en nuestro repositorio de Zammad en GitHub, enviar un pull request (o dos) o unirse al esfuerzo de traducción en Weblate. ¡La comunidad se lo agradecerá!

Dusan Vuckovic es Desarrollador de Software Senior en Zammad y un apasionado de la resolución de problemas, la innovación y las tecnologías modernas. Cuando no está creando mejores herramientas en Zammad, disfruta trabajando en proyectos paralelos, sumergiéndose en comunidades de código abierto o explorando el cosmos.

Conozca más sobre Dusan en nuestra serie Zammad Diary