Comment documenter un outil interne ?

La documentation d'un outil interne sert le jour où la personne qui sait tout est absente, où un nouvel arrivant doit être opérationnel, ou où un autre prestataire reprend l'application. Elle se néglige facilement, parce que son absence ne gêne personne tant que rien ne change.

Trois documentations pour trois publics

Mélanger ces trois publics dans un seul document produit un texte que personne ne lit : trop technique pour les uns, trop sommaire pour les autres.

Ce qu'il faut écrire en priorité

Si le temps manque, commencez par ce qui se perd le plus vite :

1. Les règles métier : pourquoi un dossier passe d'un statut à l'autre, comment un montant est calculé, quelles exceptions existent. Ces règles sont invisibles dans l'interface et coûteuses à retrouver.
2. Les rôles et leurs droits : qui peut faire quoi, et ce qui est délibérément interdit.
3. Les liaisons avec d'autres logiciels : quelle donnée circule, dans quel sens, à quelle fréquence, et que faire en cas d'échec.
4. Les procédures d'exploitation : sauvegarde, restauration, création d'un compte, remise à zéro d'un mot de passe.
5. Les décisions structurantes et leur raison, qui évitent de refaire les mêmes débats.

Écrire court et daté

• Une page par sujet, avec un titre qui pose une question pratique.
• Le vocabulaire affiché dans l'outil, pour que les mots se retrouvent à l'écran.
• Une date de dernière mise à jour sur chaque document, et le nom du responsable.
• Des captures d'écran pour les gestes, du texte pour les règles, car une capture vieillit plus vite qu'une phrase.
• Pas de duplication : une information écrite à deux endroits finit par se contredire.

La ranger là où on la cherche

Une documentation introuvable équivaut à une documentation absente. Les fiches d'usage gagnent à être accessibles depuis l'application elle-même ou depuis l'intranet, au même endroit que les autres procédures internes. La documentation technique, elle, reste avec le code, pour évoluer au même rythme que lui.

La maintenir à jour

Le seul mécanisme qui fonctionne durablement consiste à lier la mise à jour à la livraison : une évolution n'est considérée comme terminée que lorsque la documentation correspondante a été corrigée. Complétez par une relecture périodique des fiches les plus utilisées, et par un moyen simple de signaler qu'une page est devenue fausse. Une documentation partiellement fausse est plus dangereuse qu'une documentation absente, car elle inspire confiance.

Ce que la documentation protège

Au-delà du confort quotidien, elle protège contre trois situations coûteuses :

• Le départ d'une personne clé, qui emporte les règles non écrites.
• Le changement de prestataire : sans documentation, la reprise commence par une longue rétro-ingénierie, comme le détaille l'article sur la façon de reprendre une application existante.
• L'incident : restaurer une sauvegarde ou remettre un service en route s'improvise mal sous pression.

Faites figurer la remise de la documentation à jour parmi les livrables attendus au contrat, et vérifiez-la comme le reste.

NexSecure livre la documentation d'usage et technique des applications qu'elle développe, dans le cadre de son offre de développement web sur mesure.