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.

4 commentaires pour “Le jour où la documentation a disparu”

  1. Retour d’expérience factuel, j’aime bcp. Cela pose vraiment le débat sur l’utilité des référentiels de normes et sur la façon de les utiliser pour apporter plus de valeur. En lisant l’article, plusieurs questions me viennent à l’esprit : pourquoi les acteurs projets n’utilisaient pas les normes documentées ?
    – Sont ils devenus très compétents sur le sujet ?
    – Ne se sentent ils pas obligés (malgré une qualité de livrable discutable)?
    – Le mode de diffusion des normes était il inadapté ?

    Qu’avez vous fait après la suppression de la documentation ?
    avez vous opté pour de l’accompagnement projet directement ?

    Dans l’absolu, je suis convaincu que le mode ‘pousser’ crée du stock d’info qui coûte cher à maintenir (pas forcément tjrs utilisé). Alors qu’un mode ‘tirer’ c’est à dire produire/répondre à la demande des projets est bcp plus fiable.
    Mais cela dépend à mon sens bcp du contexte projet, de la compétence des ressources, du mode de fonctionnement archi/projet …

  2. > Pourquoi les acteurs projets n’utilisaient pas les normes documentées ?

    D’après moi, l’information se trouvait difficilement : la documentation se trouve dans un Wiki et l’organisation n’était pas optimale. Mais surtout, les informations utiles étaient au milieu d’autres informations, intéressantes mais non pertinentes pour le projet. Au final, les acteurs projets passaient trop de temps à trouver la bonne information.

    >Qu’avez vous fait après la suppression de la documentation ?
    >avez vous opté pour de l’accompagnement projet directement ?

    Effectivement, nous avons renforcé notre accompagnement des projets. Nous répondons à leur question directement. Ces questions, poussées par les projets, viennent enrichir une série de ‘FAQs’ très pragmatique, elle-même accompagnée par une série d’exemples d’implémentation. Ces FAQs+Exemples nous servent d’abord à expliquer la solution. Et il est possible qu’un autre projet nous posant la même question n’ait besoin que de la documentation déjà écrite.

  3. > Au final, les acteurs projets passaient trop de temps à trouver la bonne information.

    Je dirai même qu’au final les projets ne passaient pas du tout de temps à trouver l’information chez nous. Dans une logique projet on ne doit pas perdre de temps (même si c’est pour en gagner 3 fois plus par la suite). Si Google répond plus vite que notre cellule ils se tourneront chez Google. Le problème c’est que les réponses données par Google ne prennent pas en compte la spécificité de l’entreprise, son SI, …

  4. A chaque changement de mission, nouveau référentiel, nouvelle norme, nouvelles bonnes et mauvaises pratiques
    Au final, je lache l’affaire, quand on me fait une réflexion je prends note, pas le temps de lire un tas de documentation et de vision
    Au cas par cas, c’est mieux

Laissez un commentaire