Continuous Documentation – Exemple de mise en place

Parmi les livrables d’un projet, la documentation est celle qui assurera sa pérennité. Dans le cadre d’une application, la documentation technique est la garante des fonctionnalités disponibles, de leurs usages mais aussi de son architecture, son intégration et son déploiement. Par conséquent, la documentation est vouée à vivre au rythme de l’évolution de l’application, et trouve naturellement sa place aux côtés du code source de l’application. Ainsi, quels sont les outils les plus adaptés à la rédaction de la documentation pour la faire cohabiter avec les sources ?

La documentation au plus proche du code source

Tout d’abord, certains outils de gestion de sources – tel que GitHub et GitLab – proposent des fonctionnalités dédiées à la documentation comme un wiki intégré et l’interprétation des fichiers MarkDown et AsciiDoc, deux formats de texte pour la rédaction de documentations. Ces formats simples on l’avantage d’être de simples fichiers textes et sont par conséquent facilement exploitable dans un outil de gestion de sources, contrairement aux formats Word et LibreOffice. L’emplacement de la documentation technique est alors idéale car au plus proche de l’application : elle pourra évoluer et être versionnée en même temps que le code.

Cependant, cela ne convient pas à tous les usages : le référentiel de codes est rarement ouvert à tous en entreprise, et la consultation de la documentation via GitHub ou GitLab n’est pas toujours le format le plus adapté pour la consulter ou la partager. C’est pourquoi, des formats plus traditionnels comme le HTML ou le PDF sont souvent plus pratiques à l’usage, à la publication, éventuellement pour l’impression ou encore pour un classement dans une GED.

A l’instar de HTML/CSS, les documents MarkDown et AsciiDoc peuvent servir à la génération d’un document plus lisible et esthétique aux formats HTML ou PDF par exemple. En outre, AsciiDoctor est un outil pour convertir les documents AsciiDoc vers HTML, PDF ou encore DocBook.

asciidoctor

Générer la documentation à la construction de l’application

Intégrer la génération de la documentation avec la construction de l’application garantie la livraison d’une documentation à chaque version. Dans cette optique, le plugin asciidoctor-maven-plugin convertit les documents AsciiDoc pour les projets Maven. Les projets Gradle ne sont pas en reste et disposent d’un plugin équivalent : asciidoctor-gradle-plugin.

En ce qui concerne le plugin Maven, son utilisation est des plus simple :

  • déclarer le plugin dans votre fichier pom.xml,
  • placer votre documentation asciidoc dans src/main/asciidoc.

La documentation sera alors générée dans target/generated-docs en même temps que la construction du projet.

Exemple d’utilisation du asciidoctor-maven-plugin:
<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>1.5.3</version>
  <executions>
    <execution>
      <id>generate-docs-html</id> <!-- <2> -->
      <phase>prepare-package</phase>
      <goals>
        <goal>process-asciidoc</goal>
      </goals>
      <configuration>
        <backend>html</backend>
        <doctype>book</doctype>
        <attributes>
          <snippets>${snippetsDirectory}</snippets>
        </attributes>
      </configuration>
    </execution>
  </executions>
</plugin>

<1> Dépendances requises pour supporter le PDF.
<2> La première exécution du plugin génère la documentation en HTML.
<3> La seconde exécution génère la documentation en PDF.

 

Documenter les API REST

La documentation d’une API est une partie des plus fastidieuses. En effet, celle-ci décrit l’utilisation de chaque services – que ce soit la requête attendue ou la réponse qui sera émise – et les différents cas d’usage. Un travail d’autant plus pénible que les contrats de services seront amenés à évoluer au fur-et-à-mesure des versions.

Swagger et JSONDoc : solutions invasives

A cette fin, des outils tels que Swagger ou JSONDoc sont populaires. Ils agrémentent tous les deux vos API afin d’exposer votre documentation, exploitable ensuite à travers une interface Web. Séduisantes au premier abord, elles vous permettent également de tester directement vos API.

Néanmoins, ces solutions sont intrusives dans le code de votre application. D’abord, elles imposent de les embarquer dans votre application et ajoutent une surcouche à vos API même en production. De plus, leur fonctionnement implique d’insérer des annotations dédiées à la documentation au cœur même du code source, sur chaque services de l’API. Une idée séduisante initialement : avoir la documentation au plus proche du code. Malheureusement, cela tend rapidement à réduire la lisibilité du code, et limite la maintenance de la documentation uniquement aux développeurs.

Par ailleurs, ces outils ne répondent que partiellement au besoin de documentation des API REST, notamment ils ne permettent pas de décliner aisément les différents cas d’utilisation et se limitent à la seule description des services, des champs à renseigner ou des réponses. Ils n’adressent pas non plus les liens HATEOAS. Dernier mauvais point, ils ne peuvent pas être inclus dans une documentation traditionnelle comme un guide de l’utilisateur.

Spring RESTDoc : une approche via les tests

Pour ces motifs, Spring RESTDocs propose une autre approche qui combine les avantages d’une documentation écrite manuellement et de la documentation générée. Ainsi, ce framework s’introduit également dans votre application, mais uniquement dans la phase de tests : il n’introduira alors en aucun cas de désagrément à vos services en production. Il n’y sera même pas présent. Son fonctionnement reprend l’idée de s’inviter dans le code source de votre application pour être au plus près de vos API, mais contrairement à Swagger ou JSONDoc, le code de votre application n’est pas impacté. En effet, Spring RESTDocs vient enrichir vos tests unitaires !

Exemple de test unitaire incluant de la documentation:
this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document("index",
                responseFields( 
                        fieldWithPath("contact.email")
                                .description("The user's email address"), 
                fieldWithPath("contact.name").description("The user's name"))));

Dorénavant, lors de la construction du projet au moment où les tests seront exécutés, Spring RESTDocs générera des fichiers AsciiDoc contenant les requêtes et les réponses simulées lors du tests ainsi que les descriptions ajoutées dans les tests. Ensuite, ces documents pourront ensuite être inclus dans la documentation que vous avez produit pour décrire un cas d’usage. De cette façon, elle est non seulement plus lisible et plus détaillé, mais également toujours en concordance avec vos tests et par conséquent avec votre code.

Un projet exemple est disponible sur GitHub.

 

Continuous Documentation – Une pratique saine

continuous-documentation

Souvent perçue comme une corvée, la documentation est dans la plupart des cas délaissée. Au mieux elle est reportée en fin de projet, au pire elle finit à la trappe. Les raisons de cette perdition sont souvent le manque de temps ou de budget. En fin de course, il est difficile de négocier une rallonge pour rédiger de la documentation.

Pourtant, l’utilité de celle-ci fait souvent l’unanimité. Elle est un facteur clef pour le maintien en condition opérationnelle (MCO), sur l’intégration de l’application au sein du SI ou encore facilite la prise en main du projet par une nouvelle recrue.

Par ailleurs, celle-ci fait partie des bonnes pratiques de la méthodologie Agile. En effet, les préceptes de la méthodologie agile recommande d’arriver à un état livrable de votre application à la fin de chaque sprint, alors pourquoi ne pas l’y inclure?

Les bénéfices

Une documentation disponible à chaque fin de sprint/jalon

La rédaction au-fur-et-à-mesure vous garantie d’avoir une documentation synchronisée avec l’évolution de votre application. Vous éviterez ainsi l’écueil d’une application sans documentation en fin de projet, et de ne plus disposer de moyens – temps et/ou budget – pour la réaliser. De plus à la fin de chaque sprint, votre application est dans un état livrable. Elle contiendra, à minima, d’un guide de l’utilisateur, d’une notice d’installation ou d’un manuel d’exploitation. Bref, votre application prend l’air d’un produit fini et délivrable à un client.

Une documentation précise

D’autre part, vous vous rappellerez plus aisément des points les plus importants en rédigeant leurs documentations dans un délai assez court après leurs réalisations. En conséquence, votre documentation en sera d’autant plus précise.

Une documentation pour chaque version de l’application

Enfin, cette synchronisation du code et de la documentation les met dans un cycle de vie identique. Code source et documentation évoluent ensemble, et pourquoi pas versionnée ensemble. Vous disposez, alors, d’une documentation adéquate en fonction de chacune des versions de votre application. Ainsi, par exemple, la dernière version de la documentation décrit les nouveaux paramètres d’une fonctionnalité, la précédente ceux devenus obsolètes mais encore valable pour la version antérieure (tout est bien dans le meilleur des mondes).

Les écueils

Documenter au moment opportun

Les exigences sont susceptibles d’évoluer tout au long du projet, vous obligeant à retravailler la documentation pour refléter ces changements. Aussi, il est préférable de ne pas documenter trop vite ou trop souvent. Mieux vaut attendre un état stable du produit. Vous éviterez ainsi de perdre du temps et de l’argent à retravailler la documentation.

Une documentation concise et adaptée aux besoins du produit

Il n’est pas nécessaire de tout documenter. La documentation n’a pas vocation à remplacer un cahier des charges ou des spécifications techniques. Bien souvent il sera préférable d’y trouver le manuel d’utilisation (accompagné d’exemples), un guide d’intégration, la description des API, etc. De plus, mieux vaut ne pas trop en faire. La rédaction doit rester rapide et concise.

Dans un prochain article, je vous présenterai un exemple de mise en oeuvre d’une « Continuous Documentation ».

Formation Ad Hoc Java 8 – Spring 4

Dans le cadre de leurs missions de coaching technique, les experts de SALTO Consulting réalisent pour leurs clients des formations Ad Hoc destinées à mettre à niveau leurs équipes de développeurs.

La dernière en date, d’une durée de 2 jours, s’est appuyée sur un support Ad Hoc et des exemples d’implémentation concrète et a abordé les points techniques suivants :

java7JAVA 7

  • Binaires et le formatage de nombres
  • switch supporte les chaînes de caractères
  • Inférence de type pour l’instanciation des génériques
  • Libération automatique des ressources
  • Les exceptions

JAVA 8java8

  • @FunctionalInterface et lambdas
  • Référence de méthodes
  • Les méthodes default
  • Méthodes statiques dans les interfaces
  • Streams et opérations agrégées
  • Annotations de type et répétées
  • Réflexion pour les paramètres de méthodes

SPRING 4spring4

  • FrameWork conçu pour construire et définir l’infrastructure d’une application java, dont il facilite le développement et les tests.
  • Historique
  • Une multitude de projets connexes : Spring umbrella
  • Spécifications et librairies supportées
  • Simplification de la gestion des dépendances Maven
  • Intégration Java 8
  • Evolutions du conteneur
  • Débuter un nouveau projet Spring

SPRING BOOTspring-boot

  • FrameWork conçu pour simplifier et accélérer le développement d’applications Spring)
  • Créer une application
  • Conteneurs embarquées (TomCat, Jetty, Undertow)
  • Starters
  • Auto-configuration des composants Spring
  • Production-ready (métriques, health checks et configuration externalisée)
  • Environnement en ligne de commandes

SPRING DATAspring-data

FrameWork conçu pour manipuler les données par abstraction de la source de données, il est compatible avec les bases de données relationnelles ou no-sql comme :

  • JPA
  • Redis
  • Elasticsearch
  • Neo4j

SPRING WEBspring-web

  • FrameWork permettant de désigner des applications model-view-controller
  • DispatcherServlet
  • Contrôleur REST
  • Gestion des exceptions

SPRING BATCHspring-batch-project

Framework pour la réalisation de programmes qui traitent de gros volumes de données

  • Décomposition d’un batch
  • Job
  • Step

N’hésitez pas à nous contacter si ce type de formation vous intéresse.