Beirat Online-Events: Mit Sphinx-Needs komplexe Docs-as-Code-Projekte erfolgreich umsetzen

Strukturiertere Daten, sicherere Prozesse: Komplexe Docs-as-Code-Projekte erfolgreich mit Sphinx-Needs umsetzen

Wie lässt sich die lückenlose Nachverfolgbarkeit (Traceability) von Informationen in hochregulierten Branchen wie der Automobilindustrie oder der Medizintechnik sicherstellen? Wie behält man in komplexen Dokumentationsprojekten mit hunderten von Warnhinweisen, Produktvarianten und Glossarbegriffen stets die Übersicht?

Diesen anspruchsvollen Fragen widmete sich die sehr gut besuchte Online-Veranstaltung „Mit Sphinx-Needs komplexe Docs-as-Code-Projekte erfolgreich umsetzen“. Als Teil der tekom-Online-Reihe „Docs as Code“ führte Referent Stefan Schulz (Co-Maintainer von Sphinx-Needs) das Publikum durch ein ebenso tiefgründiges wie praxisnahes Thema. Der rege Austausch im Chat sowie die anschließende gemeinsame Diskussion zeigte, dass die gezeigten Ansätze den Nerv der modernen Technischen Redaktion treffen.

Das Kernprinzip: Vom einfachen Text zum intelligenten Objekt

Stefan Schulz brachte das grundlegende Konzept von Sphinx-Needs direkt auf den Punkt: Es geht darum, Inhalte im Doku-Quellcode adressierbar zu machen.

Beim der Methode „Docs as Code“ (hier umgesetzt mit der Markup-Sprache reStructuredText) ist der Doku-Quellcode das, was in den Textdateien (hier: RST-Dateien) verwaltet wird. Dort gibt es nicht nur reinen Fließtext sondern auch klar definierte Sektionen wie Überschriften, Absätze, Listen, Tabellen etc.

Sphinx-Needs erlaubt es nun, einzelne Informationseinheiten „objektorientiert“ (als sogenannte „Needs“) zu behandeln. Dadurch entstehen neue Strukturierungs-, Wiederverwendungs- und Verknüpfungsmöglichkeiten. Jeder dieser Bausteine erhält im Doku-Quellcode eine eindeutige ID, einen frei definierbarenTyp (z. B. Typ "Anforderung", "Warnhinweis" oder "Glossareintrag") und ggf. weitere Metadaten.

Dadurch werden Informationen programmatisch abfragbar, dynamisch miteinander verknüpfbar und automatisch validierbar.

Praxisnahe Lösungen für drei typische Redaktionsprobleme

Um die Theorie greifbar zu machen, nutzte der Referent ein alltägliches Beispiel: das Benutzerhandbuch für eine Kaffeemaschine. Anhand dieses Projekts demonstrierte er Lösungen für drei typische Herausforderungen:

1. Veraltete Glossare:
   Mit Sphinx-Needs wird jeder Glossareintrag als einzelner „Need“ definiert und als solcher im weiteren Dokument verwendet. Das System weiß dadurch automatisch, wo welcher Begriff im gesamten Handbuch verwendet wird, und verknüpft diese Stellen fehlerfrei.
2. Inkonsistente Warnhinweise (Single Source of Truth):
   Sicherheitskritische Warnhinweise müssen oft an mehreren Stellen identisch auftauchen. In der Live-Demo wurde gezeigt, wie ein zentral definierter Warnhinweis per ID referenziert und an verschiedenen Orten ausgegeben wird. Ändert sich das Signalwort an der Quelle, aktualisiert es sich überall von selbst.
3. Komplexes Variantenmanagement:
   Über einfache Steuerungsbefehle (Direktiven) lässt sich die Ausgabe des Handbuchs anpassen. So kann aus einer einzigen Quelle auf Knopfdruck die Dokumentation für das Basismodell oder die Premiumvariante der Kaffeemaschine erzeugt werden. Und das in verschiedensten Ausgabeformaten.

Qualitätssicherung: Abteilungsübergreifende Traceability

Ein besonderes Highlight des Vortrags war die Demonstration der abteilungsübergreifenden Nachverfolgbarkeit.

Stefan Schulz zeigte, wie eine direkte, nachweisbare Brücke zwischen einer Gefährdung aus der Risikoanalyse (z. B. Verbrennungsgefahr am heißen Dampfhahn) und dem entsprechenden Sicherheitskapitel im Anwenderhandbuch geschlagen wird.

Da diese Verknüpfungen direkt im Doku-Quellcode verankert sind, lässt sich der gesamte Build-Prozess so konfigurieren, dass er mit einer Fehlermeldung abbricht, sobald ein wichtiger Warnhinweis nicht korrekt verlinkt ist oder ein ungültiges Signalwort verwendet wurde. Diese automatisierte Qualitätskontrolle stieß auf großes Interesse im Publikum.

Lebhafte Diskussion: Der Blick über den Tellerrand

Die anschließende Fragerunde verdeutlichte das hohe Fachwissen des Auditoriums. Die Teilnehmenden zogen sofort Vergleiche zu ihrer bestehenden Tool-Landschaft:

• Abgrenzung zu XML und CCMS:
  Es entstand eine rege Diskussion darüber, wie sich Sphinx-Needs im Vergleich zu XML-basierten Redaktionssystemen oder Validierungsregeln wie Schematron schlägt. Der Referent legte dar, dass Sphinx-Needs durch die direkte Integration in Git eine deutlich schlankere, flexiblere und kollaborativere Alternative bietet, bei der Entwicklung und Redaktion in derselben Umgebung arbeiten können. Dies kann insbesondere in der teamübergreifenden Arbeit in der Softwareentwicklung von Vorteil sein.
• Anwendung im Team:
  Sehr praxisnah wurde auch die Frage diskutiert, welches technische Know-how im Redaktionsteam notwendig ist, um ein solches System aufzusetzen. Konsens war, dass die Ersteinrichtung oft eine engere Zusammenarbeit mit der Softwareentwicklung erfordert, die tägliche Arbeit an den Texten für Redakteurinnen und Redakteure nach einer kurzen Einarbeitung jedoch sehr komfortabel ist.

Fazit

Die Veranstaltung zeigte eindrücklich, wie Sphinx-Needs klassische Herausforderungen der Technischen Dokumentation aufgreift. Es bietet ein geeignetes Instrument, um die Bereiche Risikobewertung, Produktentwicklung und Anwenderdokumentation lückenlos zu verbinden.

Durch eindeutig adressierbare Informationsbausteine und automatisierte Validierungsmechanismen entsteht eine durchgängige Nachverfolgbarkeit, die Fehlerquellen eliminiert und den redaktionellen Alltag nachhaltig absichert.

Das durchweg positive Feedback der Teilnehmenden unterstrich das große Interesse an dieser praxisnahen Methodik zur Qualitätssicherung in der Technischen Redaktion.

Link zum Repository, um den gezeigten Kaffeemaschinenfall nachzuvollziehen: https://github.com/useblocks/tekom-sphinx-needs-demo