Documenter, ce troisième verbe qu'on saute toujours

Quand on me demande comment je travaille, je réponds trois verbes : je code, je teste, je documente. Les deux premiers ne surprennent personne. Le troisième fait souvent sourire, comme si c'était la corvée qu'on garde pour le vendredi après-midi.

Le verbe qu'on ne revendique jamais

Personne ne met « documentation » en avant sur un CV. On y met des frameworks, des architectures, parfois des tests. La documentation, elle, apparaît tout au plus en dernière puce d'une expérience, entre deux choses plus vendeuses. Pourtant c'est souvent le livrable dont on m'a le plus remercié.

Ce n'est pas un hasard : c'est la seule partie du travail dont la valeur n'apparaît qu'après votre départ.

En remote, ce que je n'écris pas n'existe pas

J'ai passé six ans à travailler avec des équipes que je ne rencontre jamais : le Texas, la France, le Cameroun. Six heures de décalage d'un côté, une heure de l'autre. Dans cette configuration, une question posée en fin de journée reçoit sa réponse le lendemain, et une information qui n'est écrite nulle part est une information perdue.

Ça change la façon d'écrire. On n'écrit plus pour soi, en se disant qu'on relira plus tard : on écrit pour quelqu'un qui lira sans pouvoir demander de précision. Ce n'est plus une contrainte que je subis : c'est devenu ma façon par défaut de travailler.

Dix applications, une documentation

Chez OBOSSO, je suivais en parallèle un portefeuille de cinq à dix applications du groupe : applications métier, SaaS, sites vitrine. Des besoins simultanés de nouvelles fonctionnalités, de maintenance corrective et de stabilisation de l'existant, souvent la même semaine, sur des projets différents.

Dans ce contexte, la mémoire ne tient pas. J'ai rédigé la documentation technique et les procédures d'utilisation de ce portefeuille. Elles ont été adoptées par l'équipe, et elles sont toujours utilisées. C'est l'une des contributions dont je suis le plus fier, et l'une de celles qui tiennent en une seule ligne sur un CV.

La documentation est la partie du métier dont personne ne se vante, et celle qui décide si votre remplaçant vous maudit ou pas.

Un guide d'administration vaut autant que le code

Sur la Résidence Kesla, j'ai livré une application de réservation avec son back-office : logements, séjours, paiements, galerie, newsletter. Le propriétaire n'est pas développeur. Sans document d'accompagnement, il m'aurait rappelé à chaque logement à ajouter. Et le jour où je ne réponds plus, l'outil meurt.

J'ai donc rédigé un guide d'administration et je l'ai livré en même temps que le produit. Ce n'était pas dans la demande initiale. C'est pourtant ce qui fait la différence entre un site livré et un site utilisé.

Trois règles que j'applique

Documenter la décision, pas le code. Le code dit déjà comment les choses fonctionnent. Ce qu'il ne dira jamais, c'est pourquoi on a choisi cette voie plutôt qu'une autre, et ce qu'on a écarté en chemin. C'est ça qui manque à celui qui reprend le projet.

Écrire pour celui qui arrive, pas pour celui qui sait. Une documentation lisible seulement par son auteur n'est pas une documentation, c'est un aide-mémoire. Le bon test : est-ce que quelqu'un qui découvre le projet peut faire la manipulation sans poser de question ?

Livrer la documentation avec le code, pas après. Reportée à la fin du projet, elle n'est jamais écrite : le budget est consommé, l'équipe est déjà ailleurs. Elle fait partie du livrable ou elle n'existe pas.

Ce que ça coûte, ce que ça rapporte

Documenter prend du temps, et ce temps ne se voit pas dans une démo. C'est précisément pour ça qu'on le coupe en premier quand le planning se tend.

Mais une équipe qui doit reconstituer une procédure à chaque nouvel arrivant paie ce temps dix fois. Un client qui ne sait pas administrer son outil cesse de l'utiliser. Et un développeur qui ne documente pas devient, sans le vouloir, un point de défaillance unique, ce qui n'est flatteur que jusqu'au jour où il veut passer à autre chose.