Date: 2020-03-04
- Décideurs: Alexis Janvier, Gaël Reyrol
- Ticket.s concerné.s: -
- Pull.s Request.s: #32
2020-03-25 accepted
Ce n'est jamais facile de maintenir la documentation d'un projet. Dans le cas du jobBoard, une documentation semble pourtant particulièrement importante, puisque les participants au projet ne se retrouvent qu'une fois par mois IRL et viennent d'horizons techniques très différents.
Nous avons déjà mis en place une stratégie de documentation via OpenAPI afin de documenter le coeur de l'application, c'est à dire l'API Rest du projet.
Mais il y a beaucoup de décisions qui sont difficilement "documentables" : ce sont celles qui concernent les décisions d'architecture (une API Rest ou graphQL, utilisation d'une base de données relationnelle ou de type noSQL, ...).
Et pourtant, la prise de décision sur ces sujets représente l'un des grands intérêts des Coding CaenCamp.s !
- Utilisation du wiki de Github.
- Mettre en place un outil de documentation complet, comme docusaurus.
- Utiliser des ADRs.
Option choisie : "Utiliser des ADR", parce que la solution est simple et rapide, et permet de maintenir une documentation au plus proche du code. Un ADR peut être poussé dans le code du projet en même temps qu'une Pull Request.
- Un suivi des décisions architecturales prises sur le projet
- Le format ADR est léger (fichier markdown) et correspond à nos méthodes de développement.
- La structure des ADR est compréhensible et facilite l'utilisation et la maintenance.
- Le projet ADR est bien entretenu.
- Un peu de travail supplémentaire pour les développeurs qui devront prendre un certain temps pour rédiger les ADR.