Refonte de la documentation

[brindu]

Vieux sujet que celui de la refonte de la documentation technique :

• La techno / le framework ? En y repensant je trouve de plus en plus qu'un mix de Jekyll et VueJs serait assez adéquat.
• Spécifications Open API
• Ajout d'un changelog
• Calendrier/roadmap plus clair

[brindu]

Allez je me lance concernant ce sujet qui date et sur lequel il faut qu'on avance et surtout qu'on se mette d'accord sur ce qu'on fait et comment.

Ce qu'il y a à faire

Les documentations techniques

On a de plus en plus d'APIs à documenter, et d'autres à refactor :

• API Entreprise (refonte de l'existant)
• Watchdoge (besoin de les documenter pour que les usagers les utilisent pour le monitoring au lieu de taper sur les endpoints de API Entreprise)
• API Sirene / API RNA / API RNCS (en vrai pas grand chose à redire ça peut rester en l'état)

Dans tous les cas il faut des spécs OpenAPI pour tester les requêtes, et de surcroit documenter les méta-données.

Les documentations métiers

On a besoin de documentation métier pour les deux produits : API Entreprise et Data Entreprise, assez similaires toutes les deux :

• définition métier des données renvoyées
• source de la donnée
• boucle retour de correction
• FAQ

Comment ?

Comme on ne va pas faire un nouveau projet de documentation à chaque nouvelle API, je propose deux répertoires de sources pour les documentations : un pour API Entreprise et un pour Data Entreprise (c'est déjà le cas aujourd'hui puisqu'on trouve dans la documentation technique existante les documentations des différentes API derrières). Pour chaque produit on confondrait donc les documentations technique et métier dans un même répertoire de sources.

Typiquement, la documentation de Watchdoge irait dans la doc API Entreprise.

Concernant les technos et framework à utiliser : personnellement je pense qu'on peut faire quelque chose de pas mal avec Jekyll et VueJS. J'ai refait une passe sur Jekyll dernièrement et je pense que ce serait très bien pour gérer le contenu de la doc. Je trouve que la librairie gère beaucoup de chose tout en laissant assez liberté pour qu'on ait la forme finale de documentation que l'on souhaite (technique et métier séparées, ou d'une quelconque manière fusionnées). On resterait aussi sur une techno que l'on utilise déjà (pour le site vitrine). VueJS pour le dynamisme et les specs OpenAPI interactives (là dessus il faudra refaire un point sur la lib, voire reprendre ce qu'à déjà fait @Samuelfaure à la main sur Data Entreprise).

[Haelle]

Pour l'historique : https://github.com/swagger-api/swagger-ui