You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository has been archived by the owner on Oct 9, 2020. It is now read-only.
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).
Vieux sujet que celui de la refonte de la documentation technique :
The text was updated successfully, but these errors were encountered: