Ingegnerizzare una documentazione migliore in Magna-Power
Un'unica codebase di documentazione per ogni prodotto attivo, riferimenti dei comandi generati dal firmware e manuali pubblicati in HTML, PDF e markdown per gli strumenti di IA.
Magna-Power offre più di 300.000 SKU in dieci serie di prodotti. Questa ampiezza di gamma deriva da una pianificazione accurata a lungo termine e da una progettazione deliberata di interfacce di programmazione comuni e assemblaggi configurabili. La piattaforma xGen esegue un'unica codebase firmware su alimentatori MagnaDC Serie SLx, carichi elettronici DC MagnaLOAD Serie ALx, componente aggiuntivo con diodo di blocco Modulo BDx e componente aggiuntivo ad alta stabilità Modulo DBx, con un unico set di comandi SCPI e le stesse interfacce di comunicazione su tutta la gamma. Anche gli alimentatori MagnaDC SL, XR, TS, MT e ML Series condividono lo stesso firmware e le stesse funzionalità, con opzioni comuni tra le serie. Passando da una serie all'altra, la maggior parte dei capitoli di installazione e programmazione descrive le stesse funzioni.
Un'ingegneria condivisa dovrebbe significare una documentazione condivisa; per molto tempo non è stato così. Ogni serie aveva il proprio manuale, mantenuto in modo indipendente. Una modifica a un'interfaccia condivisa doveva essere copiata in ogni manuale che la menzionava, causando una deriva dei contenuti. Un manuale riceveva la correzione; inevitabilmente altri no.
La cultura del miglioramento continuo di Magna-Power rende la situazione ancora più difficile. L'anno scorso il team di sviluppo xGen ha prodotto quasi 200 ticket tra funzionalità e correzioni in sette release software, e ogni modifica visibile al cliente deve confluire nei manuali giusti, nella stessa release, descritta correttamente. Un processo che dipende da qualcuno che noti ogni modifica e modifichi a mano diversi documenti non è scalabile. Quando resta indietro, è il cliente ad accorgersene.
Così abbiamo ricostruito la documentazione come un sistema di ingegneria: una sola codebase, componenti condivisi, build automatizzate, release versionate e riferimenti dei comandi generati dal firmware stesso. La release Snapshot 75 di questo mese porta i manuali di tutti i prodotti attivi su questo sistema.
Un'unica fonte, condivisa da ogni prodotto
Ogni serie di prodotti ha il proprio progetto di documentazione, e ogni progetto include più componenti condivisi, fissati come submodule Git: la configurazione di build e gli strumenti, il tema HTML per il web e una libreria di contenuti comuni alla sua famiglia e alla sua generazione di prodotti.
La libreria di contenuti condivisi è progettata per evitare duplicazioni. Ad esempio, il capitolo sul raffreddamento ad acqua risiedeva nel manuale della Serie TS, con copie modificate altrove. Ora esiste una sola volta, e i manuali TS, SL e ML lo includono. I dettagli specifici di una serie, come il connettore di bypass del refrigerante della Serie ML, si trovano nella stessa pagina e compaiono solo nei manuali a cui si applicano. Una correzione al contenuto comune raggiunge tutti e tre i manuali alla build successiva.
Il team di Magna-Power ha anche deciso di adottare build rigorose: gli avvisi sono errori, quindi un riferimento incrociato interrotto o una figura mancante bloccano la release invece di essere pubblicati come link non funzionanti. Questa restrizione garantisce che una modifica condivisa non possa danneggiare in silenzio un manuale affine.
Documentazione dei comandi generata dal firmware
Ogni comando SCPI è definito come dato strutturato nel codice sorgente del firmware: sintassi, parametri e relativi intervalli, forma di interrogazione, descrizione ed esempi. La build del firmware genera il parser dei comandi da quella tabella. La build della documentazione genera il capitolo di Programmazione dalla stessa tabella.
Il generatore di documentazione sa per quale famiglia di prodotti sta compilando. Ad esempio, l'alimentatore ha un comando per abilitare la propria uscita DC; un carico elettronico ha un comando per abilitare il proprio ingresso DC. Un unico insieme di definizioni produce il riferimento corretto per ogni tipo di prodotto, elencando i comandi che quel prodotto implementa effettivamente.
Il vantaggio è il tempo di risposta. Quando un ingegnere aggiunge un parametro a un comando, modifica un'unica definizione. La build firmware successiva accetta il parametro e la build della documentazione lo descrive, usando la descrizione e l'esempio dell'ingegnere stesso. Questa documentazione basata sul firmware diventa parte del processo di revisione del codice, garantendo la correttezza ed eliminando il passaggio a una terza parte.
Compilata e rilasciata con il flusso di integrazione continua
Questo processo di build viene eseguito sullo stesso server interno di integrazione continua che compila il nostro firmware, il software MagnaCTRL e gli strumenti di test e calibrazione. La documentazione è un artefatto di build come tutti gli altri: contrassegnata con una propria versione e inclusa nello stesso snapshot di release del firmware che descrive. Snapshot 75, rilasciato questo mese, abbina il firmware 0.084 ai manuali con tag SLx, ALx, BDx e DBx.
Una sola build produce tre output da un'unica fonte. HTML per i manuali web. PDF composto tramite LaTeX, per il manuale che un cliente stampa e archivia con un progetto, e markdown per i modelli linguistici di grandi dimensioni. Un unico layout LaTeX condiviso governa la tipografia, le figure e le tabelle numerate e i riferimenti incrociati in ogni manuale, fino al ridimensionamento dei disegni dimensionali alla pagina e a evitare che i nomi dei comandi vengano divisi con il trattino a fine riga.
I manuali web
I manuali web hanno anche un nuovo tema sviluppato internamente, progettato per corrispondere a magna-power.com. I disegni tecnici sono tutti grafica vettoriale, progettati per scalare in modo appropriato in una lightbox al clic, senza dover scaricare il PDF. Gli esempi di codice hanno l'evidenziazione della sintassi e un pulsante di copia. La navigazione a sinistra segue la posizione durante lo scorrimento. La modalità scura inverte i diagrammi al tratto in modo che i disegni neri su sfondo trasparente restino leggibili, mentre loghi e fotografie rimangono invariati. Le segnalazioni di Avvertenza e Attenzione riportano il simbolo di allerta di sicurezza ISO 7010 nei suoi colori standard in entrambe le modalità. I font sono ospitati localmente, consentendo un aspetto coerente quando un manuale viene salvato per l'uso offline.
Selettore della versione della documentazione
Finora era online solo l'ultima versione del manuale del prodotto, e le build precedenti venivano sovrascritte. Se avevi messo in servizio un sistema con un firmware precedente e volevi il manuale com'era allora, non c'era modo di ottenerlo (facilmente).
Ogni manuale ha ora un selettore della versione della documentazione. L'ultima release rimane all'indirizzo abituale del prodotto, e ogni release precedente è archiviata. A ogni build, il server di integrazione continua scrive un manifesto delle versioni nella radice della documentazione del prodotto, e il selettore legge quel manifesto al caricamento della pagina. Una pagina archiviata elenca quindi ogni versione pubblicata dopo la sua release, comprese quelle più recenti. Scegliendo una versione si accede alla stessa pagina in quella versione, se esiste, oppure alla pagina iniziale di quella versione, se non esiste. Le pagine archiviate riportano un banner che indica quale versione si sta leggendo, con un link all'ultima.
Le versioni della documentazione sono numerate separatamente dal firmware e vengono abbinate tramite lo snapshot di release. L'archivio inizia con questa release, quindi le build precedenti potrebbero non essere disponibili.
Manuali che puoi affidare a un assistente IA
Sempre più spesso gli ingegneri forniscono un manuale a un assistente IA e gli chiedono di scrivere uno script di test o di decodificare un registro di stato. L'estrazione del testo dai PDF può alterare l'ordine di lettura e la struttura delle tabelle, come mostra l'esempio seguente, che usa una comune libreria Python, pdftotext, per convertire una pagina da un PDF.
Ogni manuale viene ora pubblicato anche come testo semplice secondo la convenzione llms.txt: un indice nella radice del manuale, una versione Markdown di ogni pagina accanto al relativo HTML e un unico file concatenato che contiene l'intero manuale. La formattazione Markdown garantisce che titoli, tabelle e blocchi di codice rimangano intatti. Le segnalazioni di pericolo ora arrivano come blocchi etichettati, e un assistente che riassume una procedura di installazione vede gli stessi avvisi che vedrebbe una persona. I file di testo escono dalla stessa build dell'HTML, garantendo che restino sempre sincronizzati. Se quel passaggio fallisce, fallisce l'intera build invece di distribuire un manuale privo di tali file.
Trattare la documentazione come parte del prodotto ci permette di portare ogni miglioramento in tutti i manuali che ne hanno bisogno e di rilasciarlo insieme alle funzionalità che spiega. I clienti ricevono indicazioni coerenti per le proprie apparecchiature, nella versione e nel formato che meglio supportano il loro lavoro.
Esempi di documentazione di riferimento per la Serie SLx, generati dalla stessa fonte: