Die fünf wichtigsten Gründe, Ihre Schemata zu dokumentieren

Die Entwicklung von Schemata ist oft ein iterativer Prozess, und Entwickler beginnen in der Regel nicht von Grund auf neu – XML-Schemata und, zunehmend, JSON-Schemata werden oft aus bestehenden Dokumenten zusammengestellt oder von anderen Teams übernommen. Die Fähigkeit, die Beziehungen zwischen den einzelnen Komponenten eines Schemas zu erkennen und Notizen über die getroffenen Entwicklungsentscheidungen zu analysieren, ist äußerst hilfreich – doch dies ist oft unmöglich aufgrund mangelnder, aussagekräftiger Dokumentation.

Schauen wir uns einige der Gründe an, warum die Dokumentation ein integraler Bestandteil Ihrer XSD-, JSON- oder anderer Schemadevelopment sein sollte.

Vorteile der Dokumentation von XSD-Schemas

Hier sind die wichtigsten Gründe, warum Sie den Schritt der Dokumentation für Ihr nächstes Schema nicht überspringen sollten.

1. Ermöglicht eine einfache Kommunikation zwischen den Mitgliedern des Entwicklungsteams.

Die Entwicklung von Schemata ist oft ein kollaborativer Prozess, und eine klare, präzise Dokumentation hilft, Verwirrung zu vermeiden und die Produktivität zu steigern, da verschiedene Entwickler an unterschiedlichen Aspekten eines Schemas oder einer Sammlung von Schemata arbeiten. Die gegenseitige Überprüfung ist ein weiterer Prozess, der durch eine klare Dokumentation erleichtert wird, wodurch mehrere Experten ihr Fachwissen zum Inhalt des Schemas einbringen können.

2. Ermöglicht eine schnelle Einarbeitung in bestehende Projekte.

Dies steht im direkten Zusammenhang mit dem vorherigen Punkt. Code, der von einer übernommenen Firma oder einer umstrukturierten Abteilung übernommen wurde, profitiert immer von einer guten Dokumentation. Selbst wenn das Projekt ursprünglich in Ihrem Unternehmen entstanden ist, ist möglicherweise der ursprüngliche Entwickler nicht mehr verfügbar, oder die Entwicklung wurde möglicherweise in einzelnen Teilen durchgeführt, sodass keine einzelne Person das gesamte Projekt kennt.

Natürlich bestehen die meisten Projekte nicht nur aus Schemata. Für eine umfassende Analyse des bestehenden Codes ist es hilfreich, UML-Diagramme zu erstellen, um das Projekt zu dokumentieren und leicht visualisieren zu können.

3. Zentralisiert Informationen über importierte oder eingebundene Schemata.

Anstatt zahlreiche Dokumente durchsuchen zu müssen, um die darin enthaltenen Beziehungen zu ermitteln, kann die Schemadokumentation Informationen über alle zugehörigen Dokumente an einem einzigen, zentralen Ort zusammenfassen.

4. Ermöglicht es auch technisch nicht versierten Interessengruppen, Schema-Definitionen zu verstehen und zu analysieren

Da die Schemadokumentation für Menschen lesbar ist, ermöglicht sie die Zusammenarbeit mit einer Vielzahl von Experten verschiedener Fachgebiete, die das Schema verstehen und während seiner Entwicklung und Weiterentwicklung wertvolle Beiträge leisten können.

5. Automatisierte Werkzeuge machen es einfach.

Ehrlich gesagt, es gibt keinen Grund, seine Schemata nicht zu dokumentieren, wenn Software den Prozess so einfach macht. Sehen wir uns an, wie Sie dies mit einem solchen Tool, XMLSpy, umsetzen können.

XMLSpy bietet vollständig anpassbare, aber dennoch umfassende Dokumentationen für Schemata, und zwar für XSD-Schemata, JSON-Schemata und XBRL-Taxonomie-Schemata. Sehen wir uns an, wie das funktioniert.

Erstellen Sie eine XML-Schema-Dokumentation

Der XMLSpy XML-Editor bietet die automatische Generierung von Dokumentationen für XML-Schemata, JSON-Schemata, XBRL-Taxonomie-Schemata – und sogar für WSDL-Definitionen – und dieser Prozess funktioniert für alle ähnlich. Öffnen Sie das Schema-Dokument und wählen Sie im Menü "Schema-Design" die Option "Dokumentation generieren".

Sie haben die Möglichkeit, die integrierte Dokumentvorlage zu verwenden, oder, falls Sie Altova StyleVision installiert haben, können Sie Ihre eigene Vorlage mit dem gewünschten Grad an Individualisierung erstellen. Anschließend wählen Sie, ob die Dokumentation im HTML-, Word-, RTF- oder PDF-Format generiert werden soll. (Hinweis: Die PDF-Generierung erfordert, dass StyleVision auf demselben Computer installiert ist.)

Weitere Optionen ermöglichen es Ihnen, festzulegen, wie Bilder verarbeitet werden, und schließlich, welche Komponenten und Details genau dokumentiert werden sollen. Sehen wir uns die generierte Dokumentation für eine XSD-Datei an, und anschließend zeige ich Ihnen die verschiedenen Optionen zur Dokumentation von JSON- und XBRL-Schemas.

Hier ist ein Auszug aus der HTML-Dokumentation für die XSD-Datei für Berichte über Ausgaben, die im XMLSpy-Beispielprojekt enthalten ist.

Die Komponenten des Schemas werden grafisch dargestellt, zusammen mit dem zugehörigen Quellcode. Hyperlinks ermöglichen eine einfache Verknüpfung von Details zu verwandten Elementen, Attributen und Datentypen.

Die Eigenschaften und Aspekte werden übersichtlich dargestellt, um eine sofortige Analyse zu ermöglichen.

Wenn Komponenten aus anderen Schemata verwendet wurden, werden auch diese Schemata dokumentiert.

Erstellen Sie eine JSON-Schema-Dokumentation

Die zunehmende Verwendung von JSON Schema zur Validierung von JSON-Datenströmen unterstreicht auch die Bedeutung einer guten Dokumentation für diese Art von Schemata.

Die Optionen zur Generierung von Dokumentationen für JSON-Schemas sind ähnlich wie bei XSD, jedoch natürlich speziell auf JSON zugeschnitten und bieten Möglichkeiten, Details zu Eigenschaften, Arrays, Mustern und ähnlichem einzubeziehen.

XBRL-Taxonomie-Dokumentation

Nun kommen wir zu den XBRL-Taxonomien, die zu den komplexesten Schemata überhaupt sind. Die Dokumentation ist hier nicht nur für die Entwickler der Taxonomien nützlich, sondern auch für nicht-technische Stakeholder im Bereich XBRL, wie beispielsweise Buchhalter und andere Fachleute im Finanzbereich.

Im XBRL-Menü des XBRL-Taxonomie-Editors bietet der Befehl "Dokumentation erstellen" die üblichen Optionen, die diesmal speziell auf XBRL-Komponenten wie Beschriftungen und Verknüpfungsdatenbanken zugeschnitten sind.

Ob Sie mit XSD-, JSON- oder XBRL-Schemas arbeiten, die Vorteile der automatischen Dokumenterstellung zur Visualisierung, zum Verständnis und zur Kommunikation der Struktur und Beziehungen von Schemas sind vielfältig – und die Tatsache, dass Sie in XMLSpy die Dokumentation in wenigen Sekunden automatisch generieren können, beseitigt alle Hindernisse bei der Erledigung dieser Aufgabe.

Wenn Sie noch kein Kunde sind, können Sie XMLSpy 30 Tage lang kostenlos testen.