Asciidoc for the win !

Il y a quelques temps, j’avais écrit un article expliquant pourquoi les documents Office n’étaient pas de bons livrables. J’y indiquais par ailleurs qu’Asciidoc me semblait une bonne alternative.

Mais un format, ça n’est qu’un format. Une documentation, ça n’est hélas pas qu’un format technique de document. C’est aussi, avant tout, le moyen de raconter l’histoire du logiciel. Et parfois, ça n’est pas facile

A la recherche du bon format

Pas son histoire au sens biographique, mais plus son usage, son architecture, bref, l’ensemble des éléments qui contraignent son code à avoir sa structure. Autrement dit, les éléments qui donnent les réponses aux questions invraissemblables que se posent un développeur.

you_down_wit_opc-yeah_you_know_me

C’est pas que je déteste, c’est que je comprend pas l’histoire

Et ça, que j’écrive ma doc dans Word, en Asciidoc, en LaTeX, la question se pose toujours : pourquoi ces décisions ont été prises.

Heureusement, j’ai découvert il y a quelques temps le format de documentation agile de Simon Brown, qu’il documente dans la doc de Structurizr.

Regardons ensemble le sommaire :

  1. Context
  2. Functional Overview
  3. Quality Attributes
  4. Constraints
  5. Principles
  6. Software Architecture
  7. Code
  8. Data
  9. Infrastructure Architecture
  10. Deployment
  11. Development Environment
  12. Operation and Support
  13. Decision Log

Et maintenant, imaginez ce que ça donne pour votre projet. Tous les aspects sont documentés dans un seul gros document Word. C’est pénible … heureusement, là, asciidoc peut vous aider.

Je vous montre : si votre doc est en asciidoc, vous pouvez faire des include.

Et donc, vous pouvez avoir un dossier de doc qui ressemble un peu à ça

  • monprojet.adoc
  • images/ Vous mettez toutes vos images là-dedans
  • includes Et chacun des chapitres de votre doc est un document séparé dans ce dossier.
    • /00_intro.adoc
    • /01_context.adoc
    • /02_functional_overview.adoc
    • /03_quality_attributes.adoc
    • /04_constraints.adoc
    • /05_principles.adoc
    • /06_software_architecture.adoc
    • /07_code Si vous avez des éléments à détailler, n’hésitez pas à créer des sous-dossiers
      • /un_detail.adoc
    • /07_code.adoc
    • /08_data.adoc
    • /09_infrastructure_architecture.adoc
    • /10_deployment.adoc
    • /11_development_environment.adoc
    • /12_operation_and_support.adoc
    • /13_usage.adoc
    • /14_decision_log.adoc
    • /99_faq.adoc

Du coup, avec tout ça, vous avez une documentation correctement découpée, dans laquelle vous mettez vos diagrammes UML (ou autres) générés avec asciidoctor-diagram, et vous êtes content …

Bon, et puis si vous n’êtes pas contents de ce format, Simon Brown mentionne également le support d’arc42, qui a l’air tout aussi intéressant :

A un détail près.

Parfois, il y a du code que vous voulez voir généré pour le mettre dans la doc.

Par exemple, si vous utilisez le ServiceLoader de Java, savoir quelles classes implémentent une interface sans avoir à chercher dans Eclipse, c’est cool.

Tant qu’à générer la doc, pourquoi ne pas générer la doc ?

Parce qu’en fait, votre doc asciidoc, vous la générez, pas vrai ? Si vous faites du maven, vous utilisez sans doute le maven-asciidoc-plugin. Je vais faire l’hypothèse que vous êtes dans ce cas.

Et dans ce cas, si vous avez besoin d’avoir un morceau de la doc qui dépende plus directement du code, vous pouvez tout à fait … utiliser Groovy pour générer des fichiers asciidoc qui vont bien !

Typiquement, pour mon exemple, j’ai un script Groovy qui a dans son CLASSPATH tous les modules de mon application, et qui à l’aide de reflections recherche les implémentations de l’interface pour générer un tableau Asciidoc les affichant.

Et comme ce script Groovy est lancé grâce à gmaven avant la génération de la doc, cette partie est toujours à jour.

Et pour un projet multimodule ?

Pour l’instant, j’ai juste testé ça une fois, et d’une façon non satisfaisante. Comme j’arrivais sur un projet existant, j’ai simplement ajouté un module doc isolé du reste de l’application.

Je pense que j’aurais eu une doc d’une bien meilleure qualité si j’avais mis la doc dans chaque module avec des includes bien costauds dans la doc du module global (voire même des morceaux complètement générés). Evidement, dans ce genre de cas, la génération de la documentation doit également être documentée …

Donc ça marche bien ?

Oh que oui !

Ecrire de la doc est presque agréable, et les aspects générationnels sont une distraction encore plus agréable. Sans même parler de la fusion de cette doc et des différents diagrammes qui y sont intégrés.

Mais je crois qu’on peut aller encore beaucoup plus loin. Pas directement avec cette technique, mais sans doute en amont, via des graphes.

On pourrait faire encore mieux ?

Je vous donne quelques exemples.

Pour décrire votre applications, vous utilisez en fait plusieurs graphes

  • L’architecture conceptuelle (ou fonctionnelle) décrit comment les composants remplissent les fonctions
  • L’architecture applicative organise ces composants en modules
  • L’architecture technique montre comment ces composants se déploient.

Tout ça est censé être à peu près couvert par Structurizr.

Mais d’autres éléments ne le sont pas : quand je décris une organisation de classe, c’est aussi un graphe. Et un diagramme de séquence pourrait tout à fait être construit à partir du code un peu annoté.

Imaginez que je dispose d’un modèle comme celui de Structurizr, mais enrichi à la fois avec les informations du code (pour produire les différents diagrammes de bas niveau), et pour lequel je puisse générer des diagrammes via une quelconque syntaxe de recherche des noeuds dans un graphe. Je pourrais alors demander facilement des trucs comme

Dessine-moi le diagramme de séquence partant de cette interaction Javascript et incluant les échanges avec le serveur, la base de données, et le composant Java bidule

Et d’un coup, je n’ai plus un simple outil de documentation, mais un outil d’analyse et de compréhension de mon code, que je peux ensuite faire produire un truc que j’ai bien galéré à faire il y a quelques temps :

Fais-moi un diagramme de composant où les classes sont coloriés en fonction de leur dette technique

Bon, c’est une très chouette idée, et je sais à peu près comment l’implémenter … Mais c’est malheureusement encore un projet de plus. Et mon temps est déjà bien rempli.

Publicités

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s