Pour une audience de développeurs & développeuses qui souhaitent comprendre le format des données, leur signification et leur provenance
En Anglais. Parce que les développeurs & développeuses sont nécessairement anglophones. Et que des personnes souhaitant moissonner des donnés sur la fabrique de la loi au niveau global ont besoin d’une documentation en anglais.
Les données publiées à https://framagit.org/tricoteuses/open-data-assemblee-nationale sont le plus proche possible des données provenant de l’assemblée nationale. Ça évite d’avoir repenser entièrement la structure des données. Les modifications sont apportées pour:
interpréter des données non documentées (par exemple lorsque le champ listePays d’un Organe Parlementaire n’est pas documenté)
trier les données pour faciliter leur comparaison (par exemple, sans ce tri, les mandats de acteurs/PA1661.json semblent avoir été substantiellement modifiés alors qu’ils sont identiques mais dans un ordre différent et qu’un tri fait apparaître que la seule différence est l’ajout d’une collaboratrice)
Lorsque des modifications non backward compatibles sont apportées, elles sont rendues backward compatible. Par exemple si le nom des fichiers change, comme c’est arrivé lorsque acteurs et organes ont été publiées sous la forme d’un fichier par organe ou acteur au lieu d’un unique fichier les agrégeant.
La documentation portera sur ces données transformées.
Pour la conversion de schema JSON en Markdown (ou plus généralement pour convertir en documentation), json-schema.org ne propose rien.
Il y a jsonschema2md mais une première tentative tombe sur un bug de 2018 toujours pas corrigé. Les annotations descriptions et title sont parfois ignorées sans qu’il soit facile de déterminer pourquoi. Et le fichier Markdown résultant n’est pas très lisible. En conclusion ce n’est pas un bon candidat.
Il y a wetzel dont l’output semble bien mais qui ne supporte pas les références relatives $ref.
Le module sphinx semble plus fonctionnel mais ne peut être utilisé que pour RST, donc ce n’est pas une option.
Plutôt que forcer, voir écrire un petit script de conversion, une option serait d’inclure le schema JSON dans la documentation. C’est un peu verbeux mais probablement assez lisible, si les descriptions sont bien indentées.
Avant de changer l’esthetique je pense qu’il faudrait:
Ajouter les schemas JSON
Ecrire de la documentation
Et faire un peu de user research pour voir comment l’audience (c’est à dire les développeurs & développeuses) arrive a s’en débrouiller. Il y a des chances pour qu’on découvre qu’il faudrait faire différement et ce serait dommage d’avoir décoré un site qu’on va détruire ou beaucoup changer
si on me gribouille des schémas vite-fait mal fait, j’peux tenter de les mettre au propre sur un logiciel de dessin vectoriel ou de diagrammes - mais attention, j’y connais rien !
Il y a peut-être un malentendu sur la notion de “schema” dans l’expression “JSON Schema”. Les JSON schemas ne sont pas des dessins mais des (meta-)données au format JSON.
Ce n’est pas un bon choix pour écrire de la documentation. Pas seulement parce qu’il n’y a rien pour présenter un schema JSON dans la documentation. Mais aussi parce qu’il n’est pas possible d’inclure des fichiers dans une documentation. Sauf à faire un script. RST + sphinx serait plus pratique.
Ca nous avance pas plus que ça Mais ça place ce qu’on fait dans un cadre. Et ça donne aussi un texte qui explique qu’une documentation des meta données structurelles aide à la compréhension du jeu de donnée. C’est de l’enfonçage de ouverte mais… dans le cas improbable ou une personne prétend que l’effort est inutile, ça peut servir.