Bessere Dokumentation entwickeln bei Magna-Power
Eine Dokumentations-Codebasis für jedes aktive Produkt, aus der Firmware generierte Befehlsreferenzen und Handbücher, die als HTML, PDF und Markdown für KI-Werkzeuge veröffentlicht werden.
Magna-Power bietet mehr als 300.000 SKUs in zehn Produktserien an. Diese Vielfalt ist das Ergebnis sorgfältiger Langzeitplanung und gezielter Entwicklung für gemeinsame Programmierschnittstellen und konfigurierbare Baugruppen. Die xGen-Plattform betreibt eine einzige Firmware-Codebasis für die MagnaDC-Netzgeräte der SLx Series, die elektronischen DC-Lasten MagnaLOAD der ALx Series, das BDx Module als Zusatzmodul mit Sperrdiode und das DBx Module als Zusatzmodul für hohe Stabilität, jeweils mit demselben SCPI-Befehlssatz und denselben Kommunikationsschnittstellen. Auch die MagnaDC-Netzgeräte der Serien SL, XR, TS, MT und ML teilen sich dieselbe Firmware und dieselben Funktionen, mit gemeinsamen Optionen über alle Serien hinweg. Wer von einer Serie zu einer anderen wechselt, findet in den meisten Kapiteln zu Installation und Programmierung dieselben Funktionen beschrieben.
Gemeinsame Entwicklung sollte gemeinsame Dokumentation bedeuten; lange Zeit war das nicht der Fall. Jede Serie hatte ein eigenes Handbuch, das unabhängig gepflegt wurde. Eine Änderung an einer gemeinsamen Schnittstelle musste in jedes Handbuch übertragen werden, das sie erwähnte, was zu inhaltlichem Auseinanderdriften führte. Ein Handbuch erhielt die Korrektur; andere zwangsläufig nicht.
Die bei Magna-Power gelebte Kultur der kontinuierlichen Verbesserung macht die Lage noch schwieriger. Im vergangenen Jahr hat das xGen-Entwicklungsteam in sieben Software-Releases fast 200 Tickets für Funktionen und Fehlerbehebungen erstellt, und jede für Kunden sichtbare Änderung muss im selben Release in den richtigen Handbüchern landen und korrekt beschrieben sein. Ein Prozess, der darauf angewiesen ist, dass jemand jede Änderung bemerkt und mehrere Dokumente von Hand bearbeitet, skaliert nicht. Gerät er ins Hintertreffen, ist es der Kunde, der es bemerkt.
Deshalb haben wir die Dokumentation als Engineering-System neu aufgebaut: eine Codebasis, gemeinsam genutzte Komponenten, automatisierte Builds, versionierte Releases und Befehlsreferenzen, die direkt aus der Firmware generiert werden. Das in diesem Monat erscheinende Release Snapshot 75 überführt jedes Handbuch der aktiven Produkte in dieses System.
Eine Quelle, gemeinsam genutzt von jedem Produkt
Jede Produktserie hat ihr eigenes Dokumentationsprojekt, und jedes Projekt bindet mehrere gemeinsame Komponenten ein, die als Git-Submodule fest eingebunden sind: die Build-Konfiguration und Werkzeuge, das HTML-Theme für das Web und eine Bibliothek mit Inhalten, die der jeweiligen Produktfamilie und Produktgeneration gemeinsam sind.
Die gemeinsame Inhaltsbibliothek ist darauf ausgelegt, Duplikate zu vermeiden. So befand sich beispielsweise das Kapitel zur Wasserkühlung früher im Handbuch der TS Series, mit bearbeiteten Kopien an anderer Stelle. Es existiert nun nur noch einmal, und die Handbücher der TS, SL und ML binden es alle ein. Serienspezifische Details, etwa der Kühlmittel-Bypass-Anschluss der ML Series, stehen auf derselben Seite und erscheinen nur in den Handbüchern, für die sie gelten. Eine Korrektur am gemeinsamen Inhalt erreicht mit dem nächsten Build alle drei Handbücher.
Das Team von Magna-Power hat sich außerdem für strikte Builds entschieden: Warnungen gelten als Fehler, sodass ein defekter Querverweis oder eine fehlende Abbildung das Release stoppt, anstatt als toter Link ausgeliefert zu werden. Diese Einschränkung stellt sicher, dass eine gemeinsame Änderung nicht unbemerkt ein Schwester-Handbuch beschädigen kann.
Aus der Firmware generierte Befehlsdokumentation
Jeder SCPI-Befehl ist in der Firmware-Quelle als strukturierte Daten definiert: Syntax, Parameter und deren Bereiche, Abfrageform, Beschreibung und Beispiele. Der Firmware-Build erzeugt den Befehlsparser aus dieser Tabelle. Der Dokumentations-Build erzeugt das Kapitel Programmierung aus derselben Tabelle.
Der Dokumentationsgenerator weiß, für welche Produktfamilie er das Handbuch erstellt. So hat beispielsweise das Netzgerät einen Befehl zum Aktivieren seines DC-Ausgangs; eine elektronische Last hat einen Befehl zum Aktivieren ihres DC-Eingangs. Ein Satz von Definitionen liefert die jeweils richtige Referenz für jeden Produkttyp und listet die Befehle auf, die das jeweilige Produkt tatsächlich implementiert.
Der Gewinn liegt in der Durchlaufzeit. Fügt ein Entwickler einem Befehl einen Parameter hinzu, bearbeitet er eine einzige Definition. Der nächste Firmware-Build akzeptiert den Parameter, und der Dokumentations-Build beschreibt ihn anhand der eigenen Beschreibung und des Beispiels des Entwicklers. Diese firmwarebasierte Dokumentation wird Teil des Code-Review-Prozesses, was Korrektheit sicherstellt und keine Übergabe an Dritte erfordert.
Erstellt und veröffentlicht mit dem Continuous-Integration-Workflow
Dieser Build-Prozess läuft auf demselben hauseigenen Continuous-Integration-Server, der unsere Firmware, die Software MagnaCTRL sowie Test- und Kalibrierwerkzeuge kompiliert. Dokumentation ist ein Build-Artefakt wie jedes andere: mit einer eigenen Version getaggt und in denselben Release-Snapshot gebündelt wie die Firmware, die sie beschreibt. Snapshot 75, der in diesem Monat erscheint, kombiniert die Firmware 0.084 mit getaggten Handbüchern für SLx, ALx, BDx und DBx.
Ein Build erzeugt aus einer Quelle drei Ausgabeformate. HTML für die Web-Handbücher. PDF, über LaTeX gesetzt, für das Handbuch, das ein Kunde ausdruckt und zu einem Projekt ablegt, sowie Markdown für große Sprachmodelle. Ein gemeinsames LaTeX-Layout steuert in jedem Handbuch Typografie, nummerierte Abbildungen und Tabellen sowie Querverweise, bis hin zum seitengerechten Skalieren von Maßzeichnungen und dazu, Befehlsnamen nicht über einen Zeilenumbruch hinweg zu trennen.
Die Web-Handbücher
Die Web-Handbücher haben außerdem ein neues, hausintern entwickeltes Theme, das passend zu magna-power.com gestaltet wurde. Technische Zeichnungen sind durchweg Vektorgrafiken und so ausgelegt, dass sie sich per Klick in einer Lightbox passend skalieren lassen, ohne das PDF herunterladen zu müssen. Codebeispiele haben Syntaxhervorhebung und eine Kopierschaltfläche. Die linke Navigation folgt Ihrer Position beim Scrollen. Der Dark Mode invertiert Strichzeichnungen, sodass schwarze Zeichnungen auf transparentem Hintergrund lesbar bleiben, während Logos und Fotografien unverändert bleiben. Hinweise vom Typ Warnung und Vorsicht tragen in beiden Modi das Sicherheitswarnsymbol nach ISO 7010 in seinen Standardfarben. Schriften werden selbst gehostet, was ein einheitliches Erscheinungsbild gewährleistet, wenn ein Handbuch für die Offline-Nutzung gespeichert wird.
Umschalter für die Dokumentationsversion
Bisher war nur die neueste Version des Produkthandbuchs online, und ältere Builds wurden überschrieben. Wer ein System mit einer früheren Firmware in Betrieb genommen hatte und das Handbuch im damaligen Stand benötigte, hatte keine (einfache) Möglichkeit, es zu bekommen.
Jedes Handbuch hat nun einen Umschalter für die Dokumentationsversion. Das neueste Release bleibt unter der üblichen Adresse des Produkts erreichbar, und jedes frühere Release ist archiviert. Bei jedem Build schreibt der Continuous-Integration-Server ein Versionsmanifest im Dokumentationsstamm des Produkts, und der Umschalter liest dieses Manifest beim Laden einer Seite. Eine archivierte Seite listet daher jede seit ihrem Release veröffentlichte Version auf, auch neuere. Wenn Sie eine Version auswählen, gelangen Sie zur selben Seite in dieser Version, sofern sie existiert, andernfalls zur Startseite dieser Version. Archivierte Seiten zeigen ein Banner, das angibt, welche Version Sie lesen, mit einem Link zur neuesten.
Dokumentationsversionen werden getrennt von der Firmware nummeriert und über den Release-Snapshot einander zugeordnet. Das Archiv beginnt mit diesem Release, sodass frühere Builds möglicherweise nicht verfügbar sind.
Handbücher, die Sie einem KI-Assistenten übergeben können
Ingenieure übergeben einem KI-Assistenten zunehmend ein Handbuch und bitten ihn, ein Testskript zu entwerfen oder ein Statusregister zu entschlüsseln. Die Textextraktion aus PDFs kann Lesereihenfolge und Tabellenstruktur durcheinanderbringen, wie das folgende Beispiel zeigt, das die gängige Python-Bibliothek pdftotext verwendet, um eine Seite aus einem PDF zu konvertieren.
Jedes Handbuch wird nun zusätzlich als reiner Text nach der llms.txt-Konvention veröffentlicht: ein Index im Stammverzeichnis des Handbuchs, eine Markdown-Darstellung jeder Seite neben ihrer HTML-Version und eine zusammengefasste Datei mit dem gesamten Handbuch. Die Markdown-Formatierung stellt sicher, dass Überschriften, Tabellen und Codeblöcke erhalten bleiben. Gefahrenhinweise erscheinen nun als beschriftete Blöcke, und ein Assistent, der ein Installationsverfahren zusammenfasst, sieht dieselben Warnungen wie ein Mensch. Die Textdateien entstehen im selben Build wie das HTML und bleiben dadurch stets synchron. Schlägt dieser Schritt fehl, schlägt der gesamte Build fehl, anstatt ein Handbuch ohne sie auszuliefern.
Wenn wir Dokumentation als Teil des Produkts behandeln, können wir jede Verbesserung in jedes Handbuch übernehmen, das sie benötigt, und sie zusammen mit den Funktionen veröffentlichen, die sie erläutert. Kunden erhalten einheitliche Hinweise für ihre Geräte, in der Version und dem Format, die ihre Arbeit am besten unterstützen.
Beispiele für Referenzdokumentation der SLx Series, erstellt aus derselben Quelle: