Le jour où la documentation a disparu

Aujourd'hui, je veux vous parler d'un grand jour vécu dans une cellule d'architecture : le jour où l'on a supprimé la documentation.

Aujourd'hui, je veux vous parler d'un grand jour vécu dans une cellule d'architecture, le jour où l'on a supprimé la documentation.

L'équipe dans laquelle je travaillais, la cellule d'architecture, est chargée d'aider les projets à assurer la qualité de leurs développements JEE ; le tout en maintenant une bonne productivité. Un des outils mis en place pour atteindre ces objectifs est un espace documentaire composé de normes de développements, de bonnes pratiques, de méthodologies projets, de préconisations d'architectures, d'explications techniques sur différents concepts, etc. Le tout globalement nommé "Référentiel d'architecture".

Ma première mission dans cette équipe a été justement de rafraichir cette documentation -- bien que ce travail ait déjà été effectué quelques mois auparavant. Et j'ai en effet trouvé nombre de pages obsolètes ou incomplètes. J'en ai donc profité pour améliorer la documentation en enrichissant son contenu, en améliorant sa structure (afin de rendre le contenu plus accessible), en mettant l'accent sur les FAQ, la technique, les outils, la méthodologie, l'architecture d'application ... J'ai travaillé quelques semaines sur cette tâche et j'ai fait un travail plutôt correct.

Quelques mois plus tard, l'équipe (moi y compris) se re-pose la question de l'utilité de la documentation : "Est elle lue ?" - "Est elle obsolète ?" - "Est elle bien organisée ?". La conclusion : un nouveau travail sur la documentation est nécessaire. Un collègue se charge de la tâche, et au bout de quelques jours se demande comment la rendre plus sexy et surtout comment enlever "le gras", c'est-à-dire toutes ces pages, certes intéressantes, mais jamais lues par les équipes projets et qui polluent donc l'accès à l'information réellement recherchée. Guillaume, mon collègue, se voyant incapable de faire ce travail dans le temps qui lui était imparti, a alors eu l'excellente idée de faire l'inverse : "au lieu de chercher ce qu'il faut enlever, cherchons ce qu'il y a à garder". Et une façon, brutale mais efficace, de le savoir, est de tout supprimer puis d'attendre les questions "Mais où est passée la page XXX ?". Comme l'équipe a un point hebdomadaire avec chacune des équipes projet, nous aurions le retour de l'ensemble des équipes au maximum une semaine après l'opération. Après quelques débats sur ce procédé, la décision à été prise de supprimer entièrement l'espace documentaire en ne laissant que la dizaine de pages que nous utilisions nous-mêmes : Guillaume a donc mis en ligne l'espace documentaire avec 95% de contenu en moins.

Les retours des projets n'ont évidemment pas été aussi catastrophiques qu'on l'on pouvait imaginer, non, ils ont été tout à fait inexistants. Pas un seul appel pour nous demander où était passée telle information. Et après avoir vérifié que le téléphone marchait bien et avoir fait le tour des projets, nous sommes rendus à l'évidence : la documentation sur laquelle j'avais moi-même travaillé plus de deux semaines était totalement inutilisée.

Une question se pose alors, "Pourquoi a-t-on dépensé beaucoup d'efforts à écrire une documentation qui se révèle inutile ?". Une réponse possible est que l'on a confondu le but et le moyen. En effet, l'objectif initial est toujours "améliorer la productivité des développements tout en assurant leur qualité". Pour atteindre cet objectif, nous pensions, et nous pensons toujours, qu'il est impératif d'élever les compétences de chaque acteur du projet et donc de partager la connaissance. Or, nous avons pris pour acquis qu'un bon moyen de communication et de partage de connaissance était une documentation riche. Ce moyen s'est peu à peu transformé en objectif : "Avoir une documentation de qualité". Et les indicateurs que nous suivions inconsciemment étaient que la documentation soit exhaustive, qu'elle soit structurée selon plusieurs axes, etc. Lors de nos travaux sur la documentation, elle s'est avérée répondre à ces indicateurs : exhaustivité, structure... .Mais nous n'avons pas pris le temps de nous assurer de l'adéquation de notre documentation par rapport aux besoins terrains.

Au final, nous avons donc pris la décision de ne pas perdre plus de temps sur cette documentation. Nous focalisons nos efforts sur le partage de connaissance et la documentation reste un outil. Si l'on peut se passer de la documentation pour atteindre cet objectif, très bien. Si nous pensons qu'écrire un bout de documentation nous permet d'être plus performants dans ce partage de connaissance, alors nous écrivons ce bout de documentation. Ainsi, cet espace documentaire s'enrichit de façon incrémentale. Il souffre de quelques défauts, par exemple, il est loin d'être exhaustif. Mais, au moins il nous rend beaucoup plus service, car il nous aide à atteindre notre objectif premier.