Spezifikation für den weltweiten Standard von Navigationsdaten
Mit parson arbeiten wir seit fast zwanzig Jahren zusammen, und das merkt man. Das Team versteht unseren Standard bis ins Detail, bringt wertvolle Impulse für die Weiterentwicklung des Datenmodells ein und ist auch bei neuen Werkzeugen und dem Einsatz von KI immer auf der Höhe der Zeit.
Die Aufgabe
Der Navigation Data Standard definiert, wie Kartendaten zwischen Herstellern, Datenanbietern und Fahrzeugen ausgetauscht werden. NDS.Classic beschreibt dazu ein physisches Datenbankformat, das im Fahrzeug gespeichert wird. NDS.Live löst dieses Modell ab: Kartendaten werden in fachlich geschnittene Module aufgeteilt und über Services bereitgestellt. Fahrzeuge beziehen genau die Daten, die sie im Moment benötigen – aus dem Backend in der Cloud, aus dem lokalen Speicher oder aus beidem.
Für die Technische Dokumentation ändert das die Ausgangslage grundlegend. Die Spezifikation muss dort verfügbar sein, wo die Entwickler arbeiten: im Code. Die Dokumentation wird unmittelbar in den Entwicklungsprozess eingebunden, damit sie zeitgleich mit der Implementierung entsteht und Änderungen an Code und Dokumentation gemeinsam geprüft werden können.
Darüber hinaus ist eine übergreifende Systemdokumentation erforderlich, die NDS.Live als Ganzes beschreibt, zentrale Konzepte erläutert und modulübergreifende Anwendungsfälle aufgreift. Eine weitere Anforderung: Die in YAML modellierten Datenlayer für diese Anwendungsfälle müssen sich mit den NDS-eigenen Werkzeugen gegen das Datenschema validieren lassen.
Unser Ansatz: Docs-im-Code
Für NDS.Live haben wir die Modulspezifikationen vollständig in das Schema integriert. Das Datenmodell wird in der Schemasprache zserio beschrieben; die zugehörigen Erläuterungen, Konzepte und Beispiele stehen als strukturierte Kommentare unmittelbar neben den Definitionen, auf die sie sich beziehen. Schema und Beschreibung stehen in denselben Dateien und werden gemeinsam versioniert, geprüft und veröffentlicht.
Die generelle Arbeitsweise selbst ist der aus NDS.Classic vertrauten sehr ähnlich geblieben: entwicklungsbegleitende Recherche in Arbeitsgruppen, enge Abstimmung mit Architektur und Entwicklung, konsequente Terminologiearbeit, ticketbasierte Planung. Ausgetauscht haben wir die Werkzeugkette – nicht den redaktionellen Anspruch.
In der Praxis arbeiten wir so:
- Eine Quelle, kein Abgleich. Beschreibung und Datenmodell stehen in derselben Datei; das erleichtert ihre konsistente Pflege.
- Redaktion im Entwicklungsprozess. Wir arbeiten mit Git, Feature-Branches und Pull Requests. Redaktionelle Beiträge durchlaufen denselben Reviewprozess wie Quellcode – und umgekehrt reviewen wir die Modelländerungen der Entwicklung.
- Prüfbare Regeln statt unverbindlicher Prosa. Normative Anforderungen formulieren wir als eigenständige, eindeutig referenzierbare Regeln im Schema. Sie sind die Grundlage für die Zertifizierung, denn jede Regel lässt sich in einen Testfall überführen.
- Automatisierte Qualitätssicherung. Terminologie, Schreibregeln, Querverweise und Abbildungen werden bei jeder Änderung automatisiert geprüft. Fehler fallen beim Schreiben auf, nicht beim Release.
- Veröffentlichung im Developer Portal. Aus den Schemadateien und den ergänzenden Markdown-Kapiteln entsteht automatisiert das Developer Portal, eine Eigenentwicklung von NDS. Dort finden Entwicklerinnen und Entwickler Systemdokumentation, Modulreferenz, Regelwerk und Best Practices an einer Stelle – versioniert und durchsuchbar.
- Doku-Framework mit KI-Integration. Die Dokumentation wird vollständig mit Visual Studio Code geschrieben. Dabei greifen wir auf KI-Unterstützung zurück, um Entwürfe und Code-Beispiele zu generieren, Schreibregeln zu prüfen, Tickets auszulesen oder Commits in Git nachzuvollziehen. Für das Team erstellte Skills erleichtern die Qualitätskontrolle oder sorgen dafür, dass erzeugte Abbildungen unseren Style-Vorgaben entsprechen. Die fachliche und redaktionelle Verantwortung bleibt immer beim Team.
Das Ergebnis
Datenmodell und Dokumentation werden gemeinsam gepflegt, geprüft und versioniert. Das Developer Portal bündelt Modulspezifikationen, Systemdokumentation, normative Regeln und Anwendungsbeispiele als zentrale, durchsuchbare Informationsquelle für Entwicklerinnen und Entwickler. Änderungen am Datenmodell und an der Dokumentation bleiben dadurch aufeinander abgestimmt. Automatisierte Prüfungen unterstützen die Qualitätssicherung, während die enge Integration in den Entwicklungsprozess den Abstimmungsaufwand reduziert.
Erbrachte Leistungen
NDS.Live
- Inhaltsrecherche in Interviews, Workshops und Meetings der Arbeitsgruppen
- Englischsprachige Spezifikationstexte direkt im zserio-Schema sowie Systemdokumentation in Markdown
- Review von Schema- und Modelländerungen in Pull Requests, fachlich und redaktionell
- Formulierung normativer Regeln als Grundlage für Konformitätstests und Zertifizierung
- Terminologie- und Styleguide-Pflege inklusive automatisierter Prüfwerkzeuge
- Informationsarchitektur und Content-Strategie für das Developer Portal
- Konzeption und Erstellung von Diagrammen und Abbildungen
- Best Practices und Anwendungsbeispiele für typische Implementierungsfragen
- Ticketmanagement, Moderation und Protokollierung von Meetings der Arbeitsgruppen
NDS Classic (Stand eingefroren)
- Teilnahme an Arbeitsgruppenmeetings zur Klärung des Bedarfs an Known-Issues
- Erstellung von Known-Issues in DITA-XML mit dem Oxygen XML Editor
- Erstellung und Upload von PDF- und HTML-basierten Ausgabeformaten
Hier haben wir den Docs-im-Code Ansatz auf der tekom vorgestellt:
Über Navigation Data Standard (NDS) e.V.
NDS e.V. ist ein internationales Konsortium aus Automobilherstellern, Zulieferern, Kartendatenanbietern und Herstellern von Navigationssystemen. Seit 2007 entwickelt der Verein einen herstellerunabhängigen Standard für Kartendaten. Mit NDS.Live führt er den Standard in eine serviceorientierte Architektur über, die kontinuierlich aktualisierte Kartendaten und fahrzeugnahe Dienste unterstützt.