Les cinq principales raisons de documenter vos schémas

Le développement de schémas est souvent un processus itératif, et les développeurs ne commencent généralement pas à partir de zéro. Les schémas XML, et de plus en plus les schémas JSON, sont construits à partir de documents existants ou hérités d'autres équipes. La capacité de comprendre comment les différents éléments d'un schéma sont liés et d'analyser les notes concernant les choix de développement est extrêmement utile, mais elle est souvent impossible en raison du manque de documentation adéquate.

Examinons quelques-unes des raisons pour lesquelles la documentation devrait être une partie intégrante de l'élaboration de vos schémas XSD, JSON ou autres.

Avantages de la documentation des schémas XSD

Voici les principales raisons pour lesquelles vous ne devriez pas négliger la phase de documentation pour votre prochain schéma.

1. Permet une communication facile entre les membres de l'équipe de développement.

Le développement de schémas est souvent un processus collaboratif, et une documentation claire et concise permet d'éviter les confusions et d'accroître la productivité, car différents développeurs travaillent sur différents aspects d'un schéma ou d'une collection de schémas. L'examen par les pairs est un autre processus facilité par une documentation claire, permettant à plusieurs experts de donner leur avis sur le modèle de données.

2. Permet une prise en main rapide des projets existants.

Cela découle directement du point précédent. Le code provenant d'une entreprise acquise ou d'un service ayant changé de structure bénéficie toujours de la documentation. Même si le projet a été initié au sein de votre organisation, le développeur initial n'est peut-être plus disponible, ou peut-être que le développement a été réparti entre plusieurs personnes, et qu'aucune personne ne connaît l'ensemble du projet.

Bien sûr, peu de projets se limitent à des schémas. Pour une analyse complète du code existant, il est utile de générer des diagrammes UML afin de documenter et de visualiser facilement le projet.

3. Centralise les informations relatives aux schémas importés ou intégrés.

Plutôt que de devoir examiner de nombreux documents pour déterminer les relations qui les unissent, la documentation du schéma peut inclure des informations sur tous les documents connexes, regroupées en un seul endroit centralisé.

4. Permet aux parties prenantes non techniques de comprendre et d'analyser les définitions de schémas

Étant donné que la documentation des schémas est lisible par les humains, elle permet une collaboration avec un large éventail d'experts dans différents domaines, qui peuvent comprendre et apporter leur contribution pendant le développement et l'évolution des schémas.

5. Les outils automatisés facilitent la tâche.

En réalité, il n'y a aucune excuse pour ne pas documenter vos schémas, surtout lorsque les logiciels rendent cette tâche facile. Examinons comment vous pouvez le faire à l'aide d'un outil comme XMLSpy.

XMLSpy offre une documentation de schémas entièrement personnalisable, mais aussi très complète, pour les schémas XSD, les schémas JSON et les schémas de taxonomie XBRL. Examinons maintenant son fonctionnement.

Générer la documentation du schéma XML

L'éditeur XML XMLSpy permet de générer automatiquement la documentation pour les schémas XML, les schémas JSON, les taxonomies XBRL, et même les définitions WSDL. Le processus est similaire pour chacun de ces types de documents. Pour générer la documentation, ouvrez le document du schéma, puis sélectionnez "Générer la documentation" dans le menu "Conception du schéma".

Vous avez la possibilité d'utiliser le modèle de documentation intégré, ou, si vous avez installé Altova StyleVision, vous pouvez concevoir votre propre modèle avec autant de personnalisation que vous le souhaitez. Ensuite, choisissez le format de la documentation : HTML, Word, RTF ou PDF. (Remarque : la génération de documents PDF nécessite que StyleVision soit installé sur le même ordinateur.)

D'autres options vous permettent de définir la manière dont les images sont traitées, et enfin, de spécifier précisément quels composants et détails doivent être documentés. Examinons la documentation générée pour un fichier XSD, puis je vous montrerai les différentes options pour documenter les schémas JSON et XBRL.

Voici un extrait de la documentation HTML pour le schéma XSD du rapport de dépenses, inclus dans le projet d'exemples XMLSpy.

Les composants du schéma sont affichés graphiquement, ainsi que le code source correspondant, et des hyperliens permettent de consulter facilement les détails des éléments, attributs et types associés.

Les propriétés et les caractéristiques sont clairement présentées, ce qui facilite l'analyse immédiate.

Lorsque des composants provenant d'autres schémas ont été inclus, ces schémas sont également documentés.

Générer la documentation du schéma JSON

L'adoption croissante de JSON Schema pour appliquer la validation des données aux flux JSON souligne également l'importance de la documentation pour ce type de schéma.

Les options de génération de documentation pour les schémas JSON sont similaires à celles pour les schémas XSD, mais, bien sûr, spécifiques à JSON, et permettent d'inclure des détails sur les propriétés, les tableaux, les motifs, etc.

Documentation de la taxonomie XBRL

Nous arrivons maintenant aux taxinomies XBRL, qui sont parmi les schémas les plus complexes existants. La documentation est ici non seulement utile pour les développeurs de taxinomies, mais aussi pour les acteurs de l'XBRL qui ne sont pas des experts techniques, comme les comptables et les autres professionnels du secteur financier.

Disponible dans le menu XBRL de.. Éditeur de taxonomie XBRL, La commande "Générer la documentation" propose les options habituelles, mais cette fois-ci, elles sont spécifiques aux composants XBRL, tels que les étiquettes et les bases de liens.

Que vous travailliez avec des schémas XSD, JSON ou XBRL, les avantages de la génération de documentation pour visualiser, comprendre et communiquer la structure et les relations des schémas sont nombreux. De plus, le fait de pouvoir générer automatiquement de la documentation dans XMLSpy en quelques secondes élimine tout obstacle à la réalisation de cette tâche.

Si vous n'êtes pas encore client, vous pouvez télécharger XMLSpy et l'utiliser gratuitement pendant 30 jours.