La doc est un code comme les autres

Par documentation, j’entends :

• documentation utilisateur en ligne ou papier
• supports de formation (pour les différents auditoires)
• documentation d’administration fonctionnelle
• documentation d’installation
• documentation d’administration technique
• documentation d’exploitation
• documentation pour la maintenance corrective et évolutive (notamment design & tests)
• etc…

Mon propos est que la documentation est comme le code, et devrait être élaborée comme le code. Voici quelques idées qui découlent de ce principe.

Produit

Le corpus documentaire livré avec un projet gagne à être considéré comme un produit en soi.
Cet ensemble de documents doit être cohérent, un jeu de versions cohérent, et cohérent avec une version de chacun des composants de code.
Quelle différence avec un incrément de code, si ce n’est qu’il s’agit de langage naturel et de documents office au lieu de code ?

Traçabilité
Il y a une adhérence entre la documentation et le code, et une modification structurelle, dans le cadre de l’implémentation d’une user story, va engendrer un impact sur la documentation.
Le travail sur chaque user story aura un impact sur la documentation, à plusieurs endroits, mais on ne pourra pas forcément découper chaque document en paragraphe par user story (pensons par exemple à un modèle de donnée pour l’exploitation que l’on ne sait pas ramener à telle ou telle user story).
Il y a la même problématique que pour le code, avec la traçabilité code/user story.
Dans certains cas, il faudra aller jusqu’à tracer le lien entre user story et chapitre de doc (des outils existent), comme on le fait parfois pour les liens entre le code et les user story (dans les commentaires, ou dans les commentaires subversion).

Au fil de l’eau
Quelle différence entre la doc et tel ou tel aspect (au sens POA) que l’on décide de couvrir au fur et à mesure, plutôt que d’attendre à la fin, comme les transactions ou le reporting.
L’idée est de ne plus dissocier dans le temps le design, l’implémentation, la documentation, et d’adopter comme unité de travail la user story de bout en bout.
Comment s’assurer que, si on a décidé de l’écrire au fil de l’eau, la doc l’est réellement ? Comment sensibiliser l’équipe ? Faire des revues documentaires (par leurs destinataires) ?
Ce qui n’est pas revu n’est pas comptabilisé, et la user story correspondante ne l’est pas (Inclure tel incrément de tel doc dans la definition of done).
Une doc qui n’est mise à jour dans un sprint est une dette technique, dont le coût s’alourdit au fur et à mesure qu’on oublie ce que l’on a fait.

Comment se fait il que les développeurs expérimentés, qui ont déjà vu des fins de projets douloureuses, avec une documentation difficile à rattraper dans des conditions budgétaires très tendues, comment font-il pour oublier ça, et recommencent-ils à repousser sans fin la doc à l’itération suivante ?

Refactoring
Le bon niveau de doc rend le code plus facile à refactorer (vue globale du système, analyse d’impact, points de vigilance, …)
Quand on y pense, il est plus facile de réécrire le code à partir de la doc que d’analyser le code pour produire la doc,donc il serait presque plus logique de privilégier la doc sur le code.

Génération
A défaut de se demander si on peut générer une partie de la documentation, on peut l’organiser pour qu’elle soit facile à maintenir.
Une nouvelle fois, il s’agit de réflexions que l’on se fait aussi pour le code.
Si génération il y a, il faut, comme pour le code, quelque part, décrire l’information, la génération n’est qu’une mise en forme.

Auditoire
La doc est un produit, elle a donc a avoir une ergonomie, à être pensée en fonction de l’utilisation qui va en être faîte.
Si la définition de l’auditoire est trop abstraite, pourquoi ne pas définir des « persona » de la documentation, qui matérialiseraient les utilisateurs type, les administrateurs opérationnels type, l’exploitant type, … comme on le fait pour le code.

Négociation
Il faut s’assurer des attentes de l’auditoire.
J’ai vu des forets entières disparaître parce que l’on anticipait à tort les attentes de tel service ou tel organisme de contrôle, sans en débattre avec eux, sans négocier.

Politique documentaire
Définir une politique documentaire concrète et explicite, adaptée au contexte plutôt qu’appliquer une liste des modèles de doc, sans remettre en question l’usage de telle ou telle doc, ou la structure des tables de matière.
L’équipe élabore cette politique sous les contraintes des partenaires, et la revoit au fur et à mesure du projet, en intégrant les retours des lecteurs.

Documentation & Agile

Quand on parle de réduire la doc en agile, on parle de réduire la contractualisation entre les acteurs, pas la doc finale.
On prétend juste que la doc à produire in fine n’est pas la documentation utilisée en cascade pour élaborer le produit, mais bien une documentation adaptée aux personnes qui vont l’utiliser, à jour, cohérente , minimale, optimale, adaptée, fruit d’une négociation avec son lectorat.