Comment bien documenter un système informatique ?

Je crois que je n’ai jamais écrit un titre aussi pompeux.

Enfin bref, cet article s’appuie sur différentes expériences que j’ai vécues … avec plus ou moins de succès.

Avant tout, posons la situation.

Quelques hypothèses

  • Vous faites partie d’une équipe de développement logiciel (je ne sais pas si ce que je vais décrire ici marche dans d’autres situations)
  • Vous disposez d’un outil de build moderne (Maven, Gradle, ou tous leurs équivalents)
  • Je vais parler ici de système, plus que de logiciel, parce que la plupart du temps, vous développez plusieurs logiciels livrables : un site web, un back-end, des plugins ou des applications clientes, …
  • Le système que vous développez est unique : personne d’autre dans le monde ne fait le même système que vous en utilisant les specs à votre disposition (ou pas)
  • Vous pouvez créer un nouvel artefact dans votre base de code pour stocker la partie principale de votre documentation

Quelques prises de conscience utiles

Vous avez donc, que vous utilisez une méthode agile ou en V, commencé par définir l’architecture de votre système avant de développer le code, qui a donné lieu à une structure de données.

Ca, c’est pour le système que vous allez livrer. Mais avez-vous conscience de l’autre système ?

6bwCQwX

Parce que vous faite quoi de votre gestionnaire de source ? De votre chaîne d’intégration et de déploiement continu ? A ce que je sache, ces éléments sont au minimum configurés pour votre équipe (dans le cas de git, ça va vite), et dans la plupart des cas hautement personnalisés selon vos besoins. Typiquement, vous avez deux systèmes à documenter :

  1. Celui que vous allez livrer
  2. Celui qui vous permet de le livrer

Quelqu’un à l’esprit joueur pourrait y voir une forme d’inception : développer un logiciel avec un ensemble de logiciels qu’on est en train de développer …

Il vous faut documenter à la fois le système que vous livrez, et celui que vous utilisez pour livrer.

Par ailleurs, est-il judicieux de parler de votre système, ou des différentes incarnations de celui-ci ?

3Bm98kT

Parce qu’après tout, votre système va connaître de multiples incarnations :

  • Architecture logique ne décrivant que les différents composants de l’application hors de toute réalité
  • Architecture physique incluant les différents environnements
    • Environnements de dév,
      • de recette
      • de prod
    • Environnements locaux
      • en PAAS
      • dans des conteneurs Docker

Dans l’idéal, votre documentation doit pouvoir se projeter sur ces différents environnements.

Quelques outils et méthodes utiles

D’abord, mettons-nous d’accord pour dire que, comme tout le monde, vous n’avez pas envie de vous répéter. Heureusement, ce problème de la non répétition est connu depuis longtemps. Regardez par exemple cet article : Single Source Information: An Agile Best Practice for Effective Documentation. Il est un peu vieux et prône donc l’utilisation de Dita XML. Ne vous enfuyez pas tout de suite, je suis sûr que vous allez voir où je veux en venir.

Quel format de document source utiliser ?

Effectivement, il faut limiter les sources de documentation et multiplier au contraire les formats de sortie. Ca revient à dire qu’il ne faut pas utiliser Office pour créer de la documentation, et pour plusieurs raisons :

  • Le livrable et la source documentaire sont identiques
  • Le système de gestion de révision intégré est loin derrière les outils de développement à notre disposition
  • Le travail collaboratif est pratiquement impossible
  • La création de documents lourds ne marche pas
  • L’inclusion de données externes mobiles est difficile à maintenir

En face, évidement, il y a eu XML (avec Docbook et Dita). Eux aussi avaient leurs défauts

  • Une syntaxe lourde
  • Des include incroyablement difficiles à maintenir
  • La nécessité d’utiliser des éditeurs spécialisés

Du coup, on pourrait penser que LaTeX pourrait être une réponse. Malheureusement, je crois que sa syntaxe n’est pas vraiment légère.

Du coup, je recommande chaudement d’utiliser AsciiDoc.

  • La syntaxe est simple
  • Il est possible de créer des structures de documents complexes (avec les include de fragments de documents)
  • Il existe des éditeurs WYSIWYG (comme par exemple AsciidocFX) qui facilitent réellement la montée en compétence
  • Et enfin, les documents finaux peuvent être générés pendant le build de votre projet, ce qui permet de raprocher la documentation et le code

Comment dessiner les diagrammes ?

Evidement, ce qui vaut pour les documents vaut également pour les diagrammes : pourquoi utiliser Visio, yEd pour des diagrammes qui vont être partagés ?

Coup de bol, asciidoctor fournit une bibliothèque (asciidoctor-diagram) qui permet de générer un paquet de type de schémas différents en intégrant quelques bibliothèques bien pratiques, et en particulier PlantUML. C’est d’autant plus intéressant que ça limite, par la nature textuelle du diagramme, la taille du dessin qui va être créé (parce que je sais pas vous mais personnellement, quand je vois un diagramme avec plus de dix noeuds, je commence à pleurer un peu).

Quel plan utiliser ?

On arrive à l’une des questions cruciales.

Avant tout, une bonne documentation, c’est une bonne histoire. Par conséquent, tout plan de documentation qui ne permettra pas l’exposé de l’histoire du système ne pourra pas être un bon plan. Et par histoire, je ne veux pas dire son historique des décisions. Non, je parle d’une histoire au sens le plus journalistique du terme : qui ? quoi ? quand où ? comment ? et surtout pourquoi ? Si votre plan ne contient pas ces éléments sous une forme ou une autre, vous n’y arriverez pas.

Coup de bol, j’ai le bon plan. ou plutôt Simon Brown a le bon plan.

Vous connaissez Structurizr ? Non ? Eh bien allez y faire un tour, c’est très intéressant.

En revanche, à titre personnel, comme j’aime mettre plus de texte que de diagramme, je trouve sa page Documentation encore plus intéressante. Pour une raison en particulier : il y décrit le contenu d’une bonne documentation sous la forme d’un sommaire assez bien fichu. Le voici :

  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

Eh bien le plan que je vous propose de suivre, c’est celui-là précisément.

Mais comment tout ça s’organise ?

Créer un artefact de documentation pour le système livrable

Dans votre gestionnaire de source, créez votre artefact de documentation. Généralement, je crée un module maven sous le projet principal. Si j’ai plusieurs sous-systèmes, je vais créer un module maven par sous-système et les agréger ensuite par chapitre (si le chapitre existe) au niveau principal

Pour ma part, ce sera un projet maven dans lequel je vais tout de suite ajouter le plugin asciidoc avec la configuration nécessaire pour générer du PlantUML.

Dans le dossier des sources asciidoc (donc dans mon cas dans src/docs/asciidoc), créez un dossier include dans lequel vous créez un fichier asciidoc pour chacun des chapitres de la doc.

Ecrivez votre doc

Pour chacun de ces chapitres, commencez par décrire le système d’une façon générale. Ne plongez dans les détails que si ces détails sont pertinents.

Ou générez votre doc

Il y a tout un tas d’éléments pour lesquels il peut être pertinent de générer certains éléments :

  • des diagrammes de classes extraits du code
  • des listes de classes implémentant certaines interfaces (avec des propriétés utiles)

Par pitié, ne vous répétez pas : vous pouvez, et devez, générer ces informations en asciidoc à partir de votre code.

Pour ça, j’utilise de façon systématique groovy : avant la génération de la doc, j’ai des scripts Groovy qui vont générer (dans target/generated/docs) les différents documents utiles.

Générez la doc livrable

Comme les fichiers asciidoc sont dans votre doc et utilisent le même système de build, vous pouvez générer la doc à chaque livraison, et même l’inclure comme artefact de votre build.

Ca vous garantit une documentation

  • à jour (puisqu’il est facile pour les développeurs de la modifier
  • propre (parce que Asciidoc génère facilement quele chose de joli)
  • conforme aux différents besoin de doc (puisqu’on peut facilement inclure les différentes parties de la doc dans différents documents)

Et ça marche bien ?

Chaque fois que j’ai utilisé cette méthode, j’ai réussi à produire de la documentation efficace, propre, et complète. Je ne sais pas si c’est une preuve

Mais où documente-t-on le système de développement ?

Dans la partie Development Environement, tout simplement.

Ca n’est pas un peu fastidieux de tenir à jour les diagrammes PlantUML ?

Ca peut rapidement l’être, c’est pour ça que je vous présenterai bientôt les différentes solutions auxquelles je pense pour … les générer, évidement ! (je dois d’ailleurs les tester sur mes programmes Codingame).

Tout ça n’est pas un nouveau nom sur une vieille idée ?

Bien sûr que si. L’idée, c’est le litterate programming, qui a connu des dizaines d’incarnation. Celle-ci est juste un peu plus moderne.

Publicités

Cinq ans de projet, putain !

TL-DR

Dans une série d’article commençant par cinq ans, putain ! j’essaye de faire un post-mortem d’un projet d’environ 5 ans de dév. Là, je vais vous parler gestion de projet. Ca n’est peut-être pas mon rôle, mais j’y ai trempé un peu.

Ouaip, bosser sur le même projet pendant cinq ans, c’est long.

Quand on a commencé ce fichu projet, on s’est dit que ce serait bien de faire de l’agile plutôt que du n’importe quoi, comme c’était auparavant l’usage dans la boîte.

Du n’importe quoi ?

Oui : sur la première année, j’ai aidé mes collègues à finir de livrer une version du logiciel historique dont la date de livraison initiale était … avant mon arrivée dans l’entreprise. Et en fait, il a fallu toute la première année pour livrer.

Et encore, on a gagné du temps en

  • mentant pendant les comités de pilotage
  • virant la moitié des fonctionnalités
  • introduisant des gros hacks pour que ça marche

Est-ce que c’était intellectuellement satisfaisant ? Bien sûr que non. Surtout que de l’agile qui marche, j’ai déja vu ça il y a bien des années. J’étais donc plutôt déterminé à assister mon mentor local dans cette transition.

Allez on commence les assouplissements

La première chose qu’on a mis en place, curieusement, c’est un pipeline d’intégration continue. Et ça a bien marché. Parce que ça nous permettait de ne plus stresser (trop) autour des livraisons. Bien sûr, des gros paquets de code foireux ont été livrés, et des retards conséquents ont été pris. Mais le fait de disposer chaque jour d’un build complet était (et est toujours) une satisfaction profonde, parce que ça donne une existence « concrète » au produit qu’on développe.

Et puis il a fallu s’intéresser à l’amont. Les user stories, les tâches, les sprints et toute cette terminologie que je trouve rétrospectivement inutile et qui n’a en fait pas marché. Je vais essayer d’éclaircir.

Donc, on a essayé de faire du scrum (qui comme chacun le sait, est une forme d’agilité) et, à cause de notre équipe moitié intégrée, moitié distribuée, on a dû gérer nos tableaux avec un outil (qui n’est pas en cause ici).

Raconte-moi une histoire – le backlog et les stories

Evidement, dans ces tableaux, la première entrée, c’est le backlog, et dans ce backlog, on trouve les stories de notre client (en l’occurence, le marketting). Et c’est là qu’est le premier problème : faire du marketting, et réussir à exprimer un besoin, c’est loin d’être simple. Et les personnes qui s’en sont occupées n’ont sans doute pas été formées à cette tâche (mais ça, ça reviendra souvent). Du coup, on a pu rencontrer, malgré le formalisme assez classique « En tant que …, Pour …, Je voudrais .. » des problèmes assez pénibles :

  • Toutes nos stories avaient comme rôle « l’utilisateur ». Du coup, impossible de dégager différents sous-sytèmes ou autorisations qui auraient pu clarifier les choses. En fait, il a fallu attendre que le projet ait déja 4 ans pour voir émerger différents rôles.
  • Il n’y avait que rarement des demandes, et bien plus souvent des solutions … dont le réalisme prétait évidement le flan à la critique.
  • Il était également  courant de voir le contenu du backlog totallement transformé d’un sprint au suivant, essentiellement parce que le marketting avait rencontré un client avec d’autres besoins

Des défauts pénibles, donc, que je regrette vraiment de ne pas avoir tenté de corriger, d’une façon ou d’une autre.

Qu’est-ce qu’il aurait fallu améliorer ?

Notre marketting n’a jamais compris ces histoires d’agilité : pour eux, il fallait « juste livrer ». Du coup, leur expliquer que donner des rôle bien définies était difficile. Pour ça, je pense que l’approche des personaes aurait été bien pratique : mettre un nom, un visage, pour que,v raiment, les différents rôles apparaissent clairement.

De la même manière, la fourniture de solutions complètes (mais toujours incorrectes) aurait sans doute nécessité de notre part plus d’accompagnement initial, pour vraiment comprendre le besoin sous-jacent plutôt que l’implémentation proposée.

Il est chouette, ton jouet … il fait quoi ?

Cela dit, on disposait de nos stories, qu’on traduisait en paquets d’items, ce qui nous paraissait correct, jusqu’à la première fin d’itération.

Oh, oui, pardon, je parle d’itération … sans doute parce que nos sprints avaient dépassé les 6 mois, ce qui les rend assez … peu courts, dirais-je.

Et donc, à la fin d’une itération, on fait deux choses :

  1. une démonstration
  2. une rétrospective

Deux occasions d’être fier de son travail … ou pas.

Ca tourne !

La démonstration … l’occasion pour l’équipe de briller devant le marketting. Qu’est-ce qui pourrait foirer ?

Oh, plein de choses (que j’ai vu, hein)

  1. Des développeurs qui ne préparent pas de démonstration, et ne s’attendent même pas à en faire, alors que leur développement est releasé
  2. Des démos qui foirent
  3. Un marketting qui profite de la réunion pour parler d’autres parties de l’application (qui n’ont reçues aucun développement, donc)
  4. Un autre marketting qui profite lui aussi de cette réunion pour râler sur cette équipe de dév qui est toujours en retard

Et quand je dis que je les ai vues, je veux dire que je les ai toutes vues dans la même démo. Alors forcément, à la fin de la démo, l’équipe est … peu satisfaite, pour dire le moins.

Qu’est-ce qu’il aurait fallu améliorer ?

La préparation de la démo, évidement. Il aurait fallu demander à toute l’équipe si les démos étaient prêtes, et testées. Et j’insiste d’autant plus sur le second point que j’ai moi-même foiré une démo parce que je l’avais insuffisament testée. Pour le premier point, je dois bien avouer que la seule façon de s’assurer que les gens préparent une démo est de les laisser se vautrer sur scène au moins une fois.

Pour le marketting, là, c’est simple, parce que je l’ai fait la fois suivante : il ya  un ordre du jour clair à cette réunion, et si certains veulent s’en écarter, c’est à l’animateur d ela réunion (moi, sur ce coup-là) de les recadrer, ce que j’ai fait.

Et dans les coulisses

Parce qu’il y a un pendant interne à cette démo : la rétrospective.

Personnellement, j’adore ce moment où on peut tenter de proposer de nouveaux modes d’organisations.

Par exemple, c’est lors d’une de ces réunions que j’avais proposé qu’on utilise Tuleap … mais j’en reparlerais.

Bref, là aussi, c’est une réunion qu’il vaut mieux préparer …

Et comme vous devez vous y attendre, j’ai eu quelques réponses comiques aux trois questions rituelles.

Vous savez :

  1. Qu’est-ce qui a bien marché ?
  2. Qu’est-ce qui n’a pas bien marché ?
  3. Qu’est-ce qu’on peut améliorer ?

Et l’ordre est important : commencer par ce qui a bien marché permet normalement aux gens d’avoir un étatt d’esprit positif … enfin, normalement.

Mais avant d’en venir aux insultes internes, une petite astuce offerte

Tout ça, c’est la faute à Raoul.

Lors de la rétropsective, regardez bien la deuxième question : c’est la porte ouverte aux réglements de compte. Pour les éviter, l’astuce est simple, on avait une persona de mauvais développeur : Raoul Abdaloff (le nom ne doit rien au hasard, et tout à l’UMP). Et tout ce qui s’est mal passé est de sa faute. Une fois muni de ce mauvais développeur, qu’est-ce qui peut foirer ?

Tout va mal, et rien ne s’améliorera

Dans l’ensemble, ces réunions se passaient bien. Jusqu’à ce jour funeste, où trois collègues ont répondu dans un bel ensemble

Qu’est-ce qui a bien marché ?

Je sais pas

Qu’est-ce qui n’a pas bien marché ?

Tout

Qu’est-ce qu’on peut améliorer ?

Rien

Là, faut être lucide, parce que les mecs, j’ai bien eu envie de les passer par la fenêtre.

Qu’est-ce qu’il aurait fallu améliorer ?

Pour la rétropsective, pas grand chose, puisque le but du jeu était d’améliorer le processus. Et ça marchait bien !

Du coup au bout de cinq ans c’est le top ?

J’ai déja parlé du dépôt de bilan, non ?

Eh bien on peut dire que ça a tout détruit.

Aujourd’hui, il n’y a plus

  • de démos
  • de rétrospectives
  • de sprints
  • d’agilité
  • d’envie

Ca calme, non ?

Mais pourquoi ?

Au fond, l’agilité, le scrum, le lean, le kanban, tout ça, c’est mignon, mais c’est juste un mensonge.

Parce qu’en fait, ces idées se contentent de dire qu’il faut que les personnes aient envie d’améliorer leur mode de travail pour que leur mode de travail s’améliore … Autrement dit, ça permet plus de canaliser l’enthousiasme de jeunes chiens fous que de remotiver des vieux développeurs dont la culture sectaire a réduit l’enthousiasme a néant.

Et, je regrette de le dire, même mon enthousiasme a disparu dans la bataille (d’un autre côté, c’est aussi pour ça que je m’en vais).

Du coup, si je peux me permettre un conseil aux apprentis agilistes, ou à ceux qui se demandent pourquoi leur processus agile est arrêté au bord de la route : regardez vos développeurs, et vos « clients ». Est-ce qu’ils sont motivés ? Est-ce que ça leur plaît ? Est-ce qu’ils ont envie de faire mieux ? Si ça n’est pas le cas, laissez tomber tout ça, et contentez vous de faire des itérations courtes, et de durée fixe. Parce que ça, le rythme, ça aide aussi beaucoup. Et le perdre, souvent, c’est un signe que quelque chose d’autre ne va vraiment pas.

 

La prochaine frontière ? l’ALM

Dans mon message sur le dépôt de bilan, je parlais de

Un truc tout con : pour faire de l’agile, utiliser cinq outils, c’est juste idiot. je vais préciser un peu : on utilise Scrumwise pour le backlog, Google Drive pour les specs, Mantis pour les bugs, Google Spreadsheet pour donner d ela visibilité aux bugfixes …

Je dois dire que ça m’a pas mal travaillé récement. Ca m’a d’autant plus travaillé qu’en raison des contraintes externes, on nous demande ces temps-ci beaucoup de reporting concernant les corrections de bugs (un secteur du développement sur lequel il faudrait aussi que j’écrive quelque chose). Un reporting qui, naturellement, prend la forme d’un tableau Google Drive (parce que quand ton seul outil est un marteau, tous les problèmes finissent par ressembler à des clous).

J’en parlais parce qu’une nouvelle sur LinuxFr m’a récement intrigué  :  La forge libre Tuleap gagne le prix américain InfoWorld Bossie Award 2013. Ca m’avait intrigué parce que, avec Sourceforge, Origo, gitHub, on peut dire que j’ai un peu vadrouillé du côté des forges, et que si certaines fonctionnalités sont sympathiques, ça ne va pas souvent bien loin …

Enfin, pas loin, pas loin, je dois bien reconnaître que GitHub Issues est une sacrément bon sang de bonne idée. Et c’est sans doute à cause de cette bonne idée que je trouve Tuleap aussi bien : parce qu’il pousse cette diée de tracabilité du code bien plus loin. C’est expliqué dans leur doc : on peut lier une user story à un bug report, lui-même lié à un commit (et éventuellement fermé depuis le commit) et à un build du Jenkins embarqué. Et là, comme dans GitHub, il semble possible de fermer (ou tout au moins de référencer) un item dans le commit pour que tous soient liés.

Et à mon avis, c’est ça la prochaine frontière du développement.

Je m’explique.

Vous développiez comment il y a dix ans ?

Moi, je faisais du java dans mon Textpad avec un script Ant qui tentait de faire (mal) des tests. (Bon déja c’était bien j’utilisais Ant pour compiler).

Et puis JUnit est apparu pour mieux qualifier la qualité de mon code.

Et puis Hudson/Jenkins est apparu pour mieux s’assurer de la qualité de tout le code qui pouvait dépendre du mien … et pour faire tout un tas d’autre trucs.

Mais, d’un point de vue traçabilité, il manquait quand même des choses : comment savoir d’où venait – fonctionnellement – telle ou telle ligne de code ?

Rien.

Aujourd’hui, avec Git, on peut un peu plus facilement retracer une ligne de code jusqu’à un commit et – dans GitHub uniquement – à un issue qui a pu être écrit à ce sujet. Mais il manque l’aspect fonctionnel : quel est le besoin utilisateur qui a mené à ce code ?

Et c’est ça à mona vis que peut amener Tuleap : aller de la spec au code en un coup, et d’une façon qui documente clairement le process.

Bon, il y a évidement d’autres avantages, mais celui-là me paraît structurant pour une entreprise.

Oh, j’allais oublier la cerise sur le gateau : il y a un connecteur Mylyn pour que le développeur aie connaissance d’autant d’informations que possible dans son Eclipse !

Autrement dit, j’ai hâte d’essayer cet outil.

 

 

Agile ?

Grâce à mon collègue désuet, j'ai découvert ce joli petit badge de développeur expérimenté en programmation extrême. Ca me tente bien, je vais peut-être le mettre sur mon blog …

Par la même occasion, j'ai trouvé quelques articles intéressants sur ce blog, comme celui sur le bûcheron et sa scie

Un article d'autant plus intéressant qu'il ne me donne pas de réponses toutes faites, mais me pose plutôt des questions.

En effet, si je passe beaucoup de temps à faire en sorte de n'avoir à corriger les bugs qu'une fois, il y a d'autres domaines sur lesquels je me pose moins de questions, et où je laisse plus bosser mes collègues sans poser la moindre question. Mais est-ce un mal ? Je m'explique .. Quand je suis arrivé dans mon entreprise, on était deux développeurs et demi. Grâce à la croissance mondiale, on est passés à cinq développeurs, ce qui provoque naturellement l'accrétion de compétences autour de points clés : créer des versions, produire une architecture puissante et évolutive, faire rentrer des ronds dans des carrés, …

La question clé est : sur quels compétences suis-je en train de progresser, et où diable est-ce que j'exerce mon agilité ?

Pour parler franchement, je n'en sais plus rien.

Je suis toujours capable, s'il le faut, d'acquérir des compétences sur une partie du code ou une autre, de la maintenir et de la faire évoluer vers un code plus propre, plus testé, plus … comment dire … atomique (au sens où on ne peut pas faire plus petit sans perdre la fonctionnalité). Mais je n'ai plus l'impression que l'avenir du logiciel qu'on est en train de développer se situe sur le plan du code. A mon sens, tout au moins dans mon entreprise actuelle, le problème n'est plus technique, mais organisationnel. Et là, il y a beaucoup de boulot pour lequel il va bien falloir que quelqu'un se motive. Hélas, j'ai utilisé le mot maudit … "il va falloir". Je déteste réellement utiliser ce genre de phrases. Mais est-ce que j'ai vraiment envie de mouiller ma chemise là-dessus ? Voilà peut-être la question qui va de plus en plus m'agiter …

PS : pour le badge, voici un test à faire … Dont le résultat sonne comme un verdict peu flatteur :

Vos résultats :

Management : 5.88%

Ingéniérie : 30.43%