Overview

Nuestro cliente es una empresa líder en informática de imágenes con sede en EE. UU., especializada en soluciones integrales de imagen de tejido a humano, análisis y gestión de datos. Sirven a clientes farmacéuticos y de biotecnología en todas las etapas del desarrollo de medicamentos.

El cliente respalda sus operaciones con dos plataformas emblemáticas:

• Una suite de post-procesamiento de múltiples modalidades para datos de imágenes (por ejemplo, SPECT, CT, PET, MR).

• Una plataforma basada en la web para gestionar e informar sobre datos de imágenes médicas y metadatos.

El desafío 

Nos encontramos con desafíos sustanciales debido a un proceso de documentación técnica ineficiente y lento. Esto a menudo resultaba en materiales desactualizados, un sitio manual de usuario mal diseñado y un aumento en la frustración del cliente. 

Procesos de autoría ineficientes 

Los procesos y herramientas utilizadas para crear y mantener manuales de usuario obstaculizaron significativamente la publicación oportuna. Los archivos de Microsoft Word se intercambiaban repetidamente, lo que resultaba en numerosas iteraciones y amplios ciclos de retroalimentación. Se creó un desorden de documentos, con nombres de archivo inconsistentes, lo que causó confusión sobre la retroalimentación desactualizada y actual.

Aparte de autorar el contenido, los escritores tenían que aplicar un estilo de formato consistente a los archivos de MS Word. Esta tarea sola podría agregar entre 6 y 8 horas de trabajo por conjunto de documentación, retrasando el inicio del proceso de revisión final.

Publicación de contenido que consume tiempo 

Nuestro cliente publica su documentación de usuario tanto en un sitio web público como en un PDF descargable. Dado que la fuente única no se consideró durante el proceso de documentación, el contenido tuvo que convertirse dos veces. 

Este proceso creó un cuello de botella para el mantenimiento de documentos, ya que incluso un pequeño cambio requería repetir todo el proceso de conversión y carga. Además, la publicación de cambios en el contenido dependía de las canalizaciones de construcción del software, lo que ralentizaba aún más el proceso de actualización.

Pobre escalabilidad y control de versiones

A medida que se lanzaban nuevas versiones del software, el volumen de documentación asociada crecía significativamente. Cada conjunto de documentos tenía su propio sistema de versiones, que se volvía cada vez más complejo y difícil de gestionar utilizando herramientas tradicionales. Esto hacía difícil rastrear las últimas versiones y asegurar la consistencia a través de la documentación.

Procesos aislados entre desarrolladores y escritores

A pesar de ser parte del mismo proyecto, los desarrolladores y los escritores trabajaban de forma independiente, utilizando procesos aislados para completar sus tareas. Esto retrasaba el proceso de documentación, ya que no se incluía como parte del ciclo de desarrollo del software.

La solución

Nuestro cliente necesitaba una solución escalable y eficiente para mantener sus proyectos en marcha. Para abordar esto, implementamos nuevas herramientas y procesos para simplificar y optimizar el flujo de trabajo para crear, actualizar, publicar y mantener la documentación de usuario de la empresa.

El enfoque Docs-As-Code

Docs-as-code trata la documentación como una parte esencial del proceso de desarrollo, tan importante como el propio código. Los equipos utilizan las mismas herramientas y procesos que utilizan para el desarrollo de software para gestionar y mantener su documentación, asegurando que la documentación se mantenga actual y precisa a medida que el código del software evoluciona.

Después de una exhaustiva investigación y evaluación, desarrollamos el siguiente proceso optimizado:

• El contenido se redacta en MarkDown, utilizando editores de texto como Visual Code Studio o Atom. 

• Los archivos de MarkDown se suben a un sistema de control de versiones, como GitLab o GitHub.
  Las revisiones técnicas y editoriales se realizan a través de solicitudes de extracción, que requieren una serie de validaciones antes de que puedan fusionarse y construirse.

• La salida HTML se genera a través de Jekyll, un generador de sitios estáticos de código abierto.
  Colaboramos estrechamente con el equipo de UX para adaptar las plantillas mantenidas por la comunidad de Jekyll, personalizando el diseño y estilo del sitio de documentación de usuario para que coincida con la marca y la identidad visual de los productos.

• Se utilizan herramientas de CI/CD, como Jenkins y GitLab para automatizar la construcción, prueba y despliegue de la documentación. 

El nuevo proceso de publicación se completa en solo minutos, reduciendo significativamente el tiempo y esfuerzo necesarios. Sin necesidad de formatear o transcribir la documentación, el contenido se puede publicar sin problemas en múltiples destinos.

Fuente única de contenido

Utilizamos Prince13, una aplicación que convierte documentos HTML en archivos PDF aplicando CSS. El contenido se redacta una vez en Markdown y se reutiliza para renderizar tanto una fuente de contenido en línea como fuera de línea.

Control de versiones de documentación

En el desarrollo de software, pueden existir diferentes versiones y ramas del código simultáneamente. De la misma manera, realizamos control de versiones y ramificación de la documentación para generar documentación para versiones o ramas específicas del código.

Esto permite a los usuarios acceder a la documentación correspondiente a su versión particular, reduciendo la confusión y proporcionando claridad.

Correcciones de errores y actualizaciones eficientes

Almacenar la documentación en un repositorio de Git separado del código principal del producto permite una identificación y resolución más rápidas de problemas de documentación. Los ciclos de construcción de la documentación son independientes del cronograma de liberación del código, lo que permite actualizaciones más ágiles de la documentación.

Documentación ágil

El desarrollo ágil de software ha transformado el panorama de la documentación técnica. Adoptamos los principios de la metodología ágil para producir documentación que evoluciona en sincronía con el producto. Los redactores técnicos trabajan en sprints, alineando sus esfuerzos con el ritmo de los desarrolladores. Este enfoque dinámico permite actualizaciones oportunas y asegura que la documentación se mantenga relevante y actualizada a lo largo del proceso de desarrollo.

Resultados

Después de la implementación del enfoque docs-as-code, presentamos documentación de usuario web altamente escalable, receptiva y completamente actualizada.

Aparte de los beneficios operacionales, el nuevo enfoque de documentación redujo costos al aprovechar software de código abierto de última generación para mejorar los procesos de documentación.

También redujimos tiempo y esfuerzo al incluir el trabajo de documentación técnica como parte del ciclo de desarrollo ágil.