La doc va bien, ne t’en fais pas

Fri, 26 Apr 2024 17:55:09 +0000

Conférence : Devoxx France 2024
Date : 17 avril 2024
Speakers : Damien Lucas (OnePoint)
Format : Conférence (45 mn)
Slides : https://dlucasd.github.io/la-doc-va-bien-ne-t-en-fais-pas/devoxx/#/
Vidéo Youtube : https://www.youtube.com/watch?v=zQ0A75HqFuA
Repo GitHub : https://github.com/dlucasd/la-doc-va-bien-ne-t-en-fais-pas

La documentation, sujet atemporel. Travaillant sur des projets en TMA, Damien faisait le constat suivant : d’un projet à l’autre, la structure, l’organisation et le niveau d’informations de la documentation diffèrent. De temps à autres, Damien assistait à des réunions visant à restructurer la documentation. Chaque participant a sa vision. Trouver un consensus n’est pas facile.
Damien s’est ainsi demandé s’il n’existait pas clé en main un template de rédaction de la documentation, si possible Open Source et reconnu par la communauté des dévs et architectes.

Au cours de ses recherches, il est tombé sur le framework arc42 créé en 2005 par 2 allemands : Gernot Starke et Peter Hruschka. Ce template se focalise sur l’ architecture des logiciels et des systèmes. Plusieurs formats sources sont possibles en téléchargement depuis la page https://arc42.org/download : asciidoc, markdown, latex, Word, Confluence, html, Doxygen, IBM Rhapsody … Voici par exemple le template arc42 pour Word : arc42-template-FR-withhelp-docx.zip

Damien a une préférence pour l’asciidoc qui permet d’avoir une approche docs-as-code : on peut le commiter dans un repository git puis générer un document au format souhaité (ex : PDF)

Les templates arc42 au format asciidoc (extension .adoc) sont disponibles sur le repo GitHub arc42-template: une dizaine de langues est supportée dont le français.

Ce template nous guide et nous pose les bonnes questions :

Contenu : que faut-il documenter ?
Motivation : pourquoi documenter et pour qui ?
Représentation : comment documenter ? Faut-il préférer un diagramme ou une liste à puce ?

Arc42 propose de documenter une application en 12 chapitres. Chaque chapitre est lui-même généralement composé de 3 sous-parties.
Dans de ce talk, Damien s’appuie sur un projet fictif pour illustrer chacun des 12 chapitres. Ce projet consiste à développer une application de billetterie pour les JO. Il en profitera pour nous présenter des outils de génération de diagrammes (PlantUML et Mermaid), des outils de modélisation (C4 et Structurizr) et des outils de génération de documentation (avec CLI et donc intégrable à la CI).

Générateur de squelette d’application basé sur Spring Initializr

Sun, 03 Jul 2022 12:25:17 +0000

Dans une grande entreprise, le développement d’applications métiers doit respecter les règles en vigueur : normes de développement, normes de sécurité, barrière qualité, socle technique borné, intégration à l’usine de dév …
Le démarrage d’une nouvelle application Java peut être accélérée de bien des manières : usage d’outils Low Code comme Palmyra, générateur de squelettes d’application comme JHipster, utilisation d’applications blanches déclinées par catégorie d’appli (ex : batch, web), copier/coller/élagage d’une application de référence, guide de démarrage sous forme wiki … Chaque technique présente ses avantages et ses inconvénients. Mais certaines ne couvrent pas toutes les règles évoquées précédemment.
Afin d’ accélérer le développement d’une nouvelle application, mon objectif était de générer un squelette d’application minimaliste dont le code généré est parfaitement maitrisé et avec des dépendances choisies à la carte par le tech lead. Libre à lui ensuite de retravailler le code généré pour mettre en place l’architecture cible de l’application, en choisissant par exemple de partir sur une architecture hexagonale.

Bien connu des développeurs Spring Boot, je me suis appuyé sur le code backend faisant tourner le site https://start.spring.io/, à savoir le projet Spring Initializr conçu et maintenu majoritairement par Stéphane Nicoll. Léger, codé en Java, reposant sur Spring Boot et documenté, ce projet a été conçu pour être personnalisé et extensible. Cela en a fait un excellent candidat.
La première mouture de ce générateur développé en quelques jours m’aura permis de générer :

la configuration du socle Spring Boot d’entreprise
la configuration du logger permettant de standardiser les logs au format JSON
la sécurisation des API REST avec Spring Security, OpenID Connect et le SSO d’entreprise
les contrôleurs et DTO d’une API REST à partir d’une spécification OpenAPI 3
le Dockerfile et la configuration du pipeline CI/CD

Openapi on Java & Moi

La doc va bien, ne t’en fais pas

Générateur de squelette d’application basé sur Spring Initializr