Vijf belangrijke redenen om uw schema's te documenteren

Het ontwikkelen van een schema is vaak een iteratief proces, en ontwikkelaars beginnen doorgaans niet helemaal opnieuw. XML-schema's, en steeds vaker JSON-schema's, worden samengesteld uit bestaande documenten of overgenomen van andere teams. Het vermogen om te begrijpen hoe de verschillende onderdelen van een schema met elkaar samenhangen en om aantekeningen over de gemaakte ontwikkelingskeuzes te analyseren, is enorm waardevol, maar dit is vaak onmogelijk vanwege het ontbreken van goede documentatie.

Laten we eens kijken naar enkele redenen waarom documentatie een integraal onderdeel moet zijn van uw XSD-, JSON- of andere schema-ontwikkeling.

Voordelen van XSD-schema documentatie

Hier zijn de belangrijkste redenen waarom u de documentatiefase niet mag overslaan bij het maken van uw volgende schema.

1. Maakt eenvoudige communicatie mogelijk tussen de leden van het ontwikkelingsteam.

Schema-ontwikkeling is vaak een samenwerkingsproces, en duidelijke, beknopte documentatie helpt verwarring te voorkomen en de productiviteit te verhogen, omdat verschillende ontwikkelaars aan verschillende aspecten van een schema of een verzameling schema's werken. Peer review is een ander proces dat wordt vergemakkelijkt door duidelijke documentatie, waardoor meerdere experts hun mening kunnen geven over het datamodel.

2. Maakt een snelle integratie van bestaande projecten mogelijk.

Dit sluit nauw aan bij het bovenstaande punt. Code die is overgenomen van een overgenomen bedrijf of een overgehelde afdeling, is altijd beter met documentatie. Zelfs als het project oorspronkelijk bij uw organisatie is ontstaan, is de oorspronkelijke ontwikkelaar mogelijk niet meer beschikbaar, of misschien is de ontwikkeling in stukken verdeeld en kent geen enkele persoon het hele project.

Natuurlijk bestaan de meeste projecten niet alleen uit schema's. Voor een volledige analyse van bestaande code is het nuttig om UML-diagrammen te genereren om het project te documenteren en gemakkelijk te visualiseren.

3. Centraliseert informatie over geïmporteerde of opgenomen schema's.

In plaats van door talloze documenten te moeten zoeken om de relaties daartussen te achterhalen, kan schema-documentatie informatie over alle gerelateerde documenten op één centrale plaats bevatten.

4. Maakt het voor niet-technische belanghebbenden mogelijk om schema-definities te begrijpen en te analyseren

Omdat de documentatie van schema's leesbaar is voor mensen, opent dit de mogelijkheid tot samenwerking met een breed scala aan experts op verschillende vakgebieden, die de schema's kunnen begrijpen en input kunnen leveren tijdens de ontwikkeling en verdere uitwerking ervan.

5. Geautomatiseerde tools maken het eenvoudig.

Eerlijk gezegd, er is geen excuus om uw schema's niet te documenteren, zeker als software het proces zo eenvoudig maakt. Laten we eens kijken hoe u dit kunt doen met een van dergelijke tools: XMLSpy.

XMLSpy biedt volledig aanpasbare, maar tegelijkertijd uitgebreide, documentatie voor schema's, zoals XSD-schema's, JSON-schema's en XBRL-taxonomieën. Laten we eens kijken hoe dit werkt.

Genereer documentatie voor het XML-schema

De XMLSpy XML-editor biedt automatische documentgeneratie voor XML-schema's, JSON-schema's, XBRL-taxonomieën – en zelfs WSDL-definities – en het proces werkt op een vergelijkbare manier voor elk type. Open het schema-document en selecteer vervolgens "Documentatie genereren" in het menu "Schema-ontwerp".

U heeft de optie om de ingebouwde documentatie-sjabloon te gebruiken, of, als u Altova StyleVision geïnstalleerd heeft, kunt u uw eigen sjabloon ontwerpen met zoveel aanpassingen als u nodig heeft. Vervolgens kunt u kiezen of u de documentatie wilt genereren in HTML, Word, RTF of PDF. (Let op: het genereren van PDF-bestanden vereist dat StyleVision op dezelfde computer is geïnstalleerd.)

Andere opties stellen u in staat om te bepalen hoe afbeeldingen worden verwerkt, en ten slotte, welke componenten en details er precies worden gedocumenteerd. Laten we eens kijken naar de gegenereerde documentatie voor een XSD-bestand, en daarna laat ik u de verschillende opties zien voor het documenteren van JSON- en XBRL-schema's.

Hieronder vindt u een fragment van de HTML-documentatie voor het XSD-bestand voor kostenrapporten, dat is opgenomen in het XMLSpy-voorbeeldenproject.

De componenten van het schema worden grafisch weergegeven, samen met de bijbehorende broncode. Hyperlinks maken het eenvoudig om details van gerelateerde elementen, attributen en types met elkaar te verbinden.

De eigenschappen en aspecten worden duidelijk weergegeven, zodat een directe analyse mogelijk is.

Wanneer componenten uit andere schema's zijn opgenomen, dan worden die schema's ook gedocumenteerd.

Genereer documentatie voor JSON-schema's

Het toenemende gebruik van JSON Schema om datavalidatie toe te passen op JSON-stromen, onderstreept het belang van documentatie voor dit type schema.

De opties voor het genereren van documentatie voor JSON Schema zijn vergelijkbaar met die voor XSD, maar zijn uiteraard specifiek voor JSON, met mogelijkheden om details op te nemen over eigenschappen, arrays, patronen, enzovoort.

XBRL-taxonomie documentatie

Nu komen we bij de XBRL-taxonomieën, die tot de meest complexe structuren behoren. De documentatie is hier niet alleen nuttig voor de ontwikkelaars van de taxonomieën, maar ook voor niet-technische belanghebbenden bij XBRL, zoals accountants en andere professionals die betrokken zijn bij de financiële aspecten.

In het XBRL-menu van de XBRL-taxonomie-editor biedt de optie "Documentatie genereren" de gebruikelijke mogelijkheden, maar dan specifiek voor XBRL-componenten zoals labels en linkdatabases.

Of u nu werkt met XSD-, JSON- of XBRL-schema's, de voordelen van het genereren van documentatie voor het visualiseren, begrijpen en communiceren van de structuur en relaties van schema's zijn talrijk. En het feit dat u documentatie automatisch kunt genereren in XMLSpy in slechts enkele seconden, elimineert alle obstakels om uw werk te voltooien.

Als u nog geen klant bent, kunt u XMLSpy 30 dagen gratis uitproberen.