Ingeniería de una mejor documentación en Magna-Power

Magna-Power ofrece más de 300 000 SKU en diez series de productos. Esa amplitud es el resultado de una planificación cuidadosa a largo plazo y de un diseño deliberado de interfaces de programación comunes y ensamblajes configurables. La plataforma xGen ejecuta una única base de código de firmware en las fuentes de alimentación MagnaDC de la Serie SLx, las cargas electrónicas de CC MagnaLOAD de la Serie ALx, el complemento de diodo de bloqueo Módulo BDx y el complemento de alta estabilidad Módulo DBx, con un único conjunto de comandos SCPI y las mismas opciones de interfaz de comunicación en todos ellos. Las fuentes de alimentación MagnaDC de las Series SL, XR, TS, MT y ML comparten igualmente el mismo firmware y las mismas funciones, con opciones comunes entre series. Al pasar de una serie a otra, la mayoría de los capítulos de instalación y programación describen las mismas funciones.

La ingeniería compartida debería implicar documentación compartida; durante mucho tiempo no fue así. Cada serie tenía su propio manual, mantenido de forma independiente. Un cambio en una interfaz compartida tenía que copiarse en todos los manuales que la mencionaban, lo que provocaba divergencias de contenido. Un manual recibía la corrección; inevitablemente, otros no.

La cultura de mejora continua de Magna-Power complica aún más la situación. El año pasado, el equipo de desarrollo de xGen generó casi 200 tickets de funciones y correcciones en siete versiones de software, y cada cambio visible para el cliente debe llegar a los manuales correctos, en la misma versión y con una descripción correcta. Un proceso que depende de que alguien detecte cada cambio y edite a mano varios documentos no escala. Cuando se queda atrás, es el cliente quien lo descubre.

Por ello reconstruimos la documentación como un sistema de ingeniería: una única base de código, componentes compartidos, compilaciones automatizadas, versiones etiquetadas y referencias de comandos generadas a partir del propio firmware. La versión Snapshot 75 de este mes lleva todos los manuales de los productos activos a ese sistema.

Una única fuente, compartida por todos los productos

Cada serie de productos tiene su propio proyecto de documentación, y cada proyecto incorpora varios componentes compartidos, fijados como submódulos de Git: la configuración de compilación y las herramientas, el tema HTML web y una biblioteca de contenido común a su familia y a su generación de productos.

La biblioteca de contenido compartido está diseñada para evitar la duplicación. Por ejemplo, el capítulo de refrigeración por agua antes residía en el manual de la Serie TS, con copias editadas en otros lugares. Ahora existe una sola vez, y los manuales de las series TS, SL y ML lo incluyen. Los detalles específicos de cada serie, como el conector de derivación del refrigerante de la Serie ML, se encuentran en esa misma página y aparecen solo en los manuales a los que se aplican. Una corrección en el contenido común llega a los tres manuales en la siguiente compilación.

El equipo de Magna-Power también optó por compilaciones estrictas: las advertencias se tratan como errores, de modo que una referencia cruzada rota o una figura ausente detiene la publicación en lugar de llegar como un enlace muerto. Esta restricción garantiza que una edición compartida no pueda dañar silenciosamente un manual hermano. 

Documentación de comandos generada a partir del firmware

Cada comando SCPI se define como datos estructurados en el código fuente del firmware: sintaxis, parámetros y sus rangos, forma de consulta, descripción y ejemplos. La compilación del firmware genera el analizador de comandos a partir de esa tabla. La compilación de la documentación genera el capítulo de Programación a partir de la misma tabla.

El generador de documentación sabe para qué familia de productos está compilando. Por ejemplo, la fuente de alimentación tiene un comando para habilitar su salida de CC; una carga electrónica tiene un comando para habilitar su entrada de CC. Un único conjunto de definiciones produce la referencia correcta para cada tipo de producto, con los comandos que ese producto realmente implementa.

La ventaja es el tiempo de respuesta. Cuando un ingeniero añade un parámetro a un comando, edita una sola definición. La siguiente compilación del firmware acepta el parámetro y la compilación de la documentación lo describe, usando la propia descripción y el ejemplo del ingeniero. Esta documentación basada en el firmware pasa a formar parte del proceso de revisión de código, lo que garantiza su exactitud y evita traspasos a un tercero.

Compilada y publicada con un flujo de trabajo de integración continua

Este proceso de compilación se ejecuta en el mismo servidor interno de integración continua que compila nuestro firmware, el software MagnaCTRL y las herramientas de prueba y calibración. La documentación es un artefacto de compilación como cualquier otro: se etiqueta con su propia versión y se incluye en el mismo snapshot de publicación que el firmware que describe. Snapshot 75, publicado este mes, empareja el firmware 0.084 con los manuales etiquetados de SLx, ALx, BDx y DBx.

Una sola compilación produce tres salidas a partir de una única fuente. HTML para los manuales web. PDF compuesto mediante LaTeX, para el manual que el cliente imprime y archiva con un proyecto, y markdown para los modelos de lenguaje de gran tamaño. Un diseño LaTeX compartido rige la tipografía, las figuras y tablas numeradas y las referencias cruzadas de todos los manuales, hasta el punto de escalar los planos dimensionales a la página y evitar que los nombres de los comandos se dividan con guion al final de una línea.

Los manuales web

Los manuales web también cuentan con un nuevo tema desarrollado internamente, diseñado para combinar con magna-power.com. Los dibujos técnicos son gráficos vectoriales, diseñados para escalarse adecuadamente en un lightbox al hacer clic, sin necesidad de descargar el PDF. Los ejemplos de código incluyen resaltado de sintaxis y un botón de copiar. La navegación izquierda sigue su posición mientras se desplaza. El modo oscuro invierte los diagramas de líneas para que los dibujos negros sobre fondo transparente sigan siendo legibles, mientras que los logotipos y las fotografías no se modifican. Los recuadros de Advertencia y Precaución incluyen el símbolo de alerta de seguridad ISO 7010 en sus colores estándar en ambos modos. Las fuentes están alojadas localmente, lo que permite una apariencia coherente cuando un manual se guarda para uso sin conexión.

Selector de versión de la documentación

Hasta ahora, solo la última versión del manual del producto estaba en línea, y las compilaciones anteriores se sobrescribían. Si ponía en servicio un sistema con un firmware anterior y quería el manual tal como era entonces, no había forma de obtenerlo (fácilmente).

Cada manual cuenta ahora con un selector de versión de la documentación. La última versión permanece en la dirección habitual del producto y todas las versiones anteriores se archivan. En cada compilación, el servidor de integración continua escribe un manifiesto de versiones en la raíz de la documentación del producto, y el selector lee ese manifiesto al cargar una página. Por lo tanto, una página archivada muestra todas las versiones publicadas desde su lanzamiento, incluidas las más recientes. Al elegir una versión, se accede a la misma página en esa versión si existe, y a la portada de esa versión si no existe. Las páginas archivadas incluyen un banner que indica qué versión se está leyendo, con un enlace a la más reciente.

Las versiones de la documentación se numeran por separado del firmware y se emparejan mediante el snapshot de publicación. El archivo comienza con esta versión, por lo que es posible que las compilaciones anteriores no estén disponibles.

Manuales que puede entregar a un asistente de IA

Cada vez más ingenieros entregan un manual a un asistente de IA y le piden que redacte un script de prueba o que interprete un registro de estado. La extracción de texto de un PDF puede alterar el orden de lectura y la estructura de las tablas, como muestra el ejemplo siguiente, que utiliza pdftotext, una biblioteca común de Python, para convertir una página de un PDF. 

Ahora cada manual también se publica como texto plano siguiendo la convención llms.txt: un índice en la raíz del manual, una versión en Markdown de cada página junto a su HTML y un único archivo concatenado con el manual completo. El formato Markdown garantiza que los encabezados, las tablas y los bloques de código se conserven intactos. Los recuadros de peligro ahora se presentan como bloques etiquetados, y un asistente que resume un procedimiento de instalación ve las mismas advertencias que vería una persona. Los archivos de texto salen de la misma compilación que el HTML, lo que garantiza que siempre estén sincronizados. Si ese paso falla, falla toda la compilación en lugar de publicar un manual sin ellos.

Tratar la documentación como parte del producto nos permite llevar cada mejora a todos los manuales que la necesitan y publicarla junto con las funciones que explica. Los clientes obtienen una guía coherente para sus equipos, en la versión y el formato que mejor respaldan su trabajo.

Ejemplos de documentación de referencia para la Serie SLx, generados a partir de la misma fuente:

• HTML
• PDF
• Markdown para LLM