Votre application métier tourne, un prestataire ou un salarié la maintient, et tout va bien tant que cette personne répond au téléphone. La maintenance logiciel devient fragile le jour où le savoir de l'application tient dans une seule tête. Cet article décrit les cinq documents qui rendent cette maintenance transmissible, et comment les faire vivre sans en faire un chantier interminable.

Pourquoi la maintenance logiciel dépend d'abord de ce qui n'est pas dans le code

Un code source dit avec précision ce que l'application fait. Il ne dit ni pourquoi tel choix a été retenu, ni comment relancer le service après une panne, ni où se trouve le compte qui envoie les courriels. Ces informations manquantes sont celles dont dépend n'importe quel nouvel intervenant, et ce sont celles qui disparaissent en premier lors d'un départ.

Le programme de recherche DORA, qui étudie les pratiques des équipes de développement, note dans son rapport 2022 que la qualité de la documentation amplifie l'effet des bonnes pratiques techniques : une même pratique, intégration continue ou gestion de versions, produit davantage de résultats dans les équipes qui documentent bien. Autrement dit, la documentation n'est pas un supplément administratif, elle multiplie la valeur de ce que vous avez déjà mis en place.

Pour une PME, l'enjeu est encore plus concret : c'est la réversibilité. Pouvoir changer de prestataire, ou reprendre la main en interne, sans repartir de zéro ni payer une seconde fois pour comprendre ce qui existe déjà.

Les cinq documents qui rendent une maintenance transmissible

1. Le dossier d'installation reproductible

Il décrit, étape par étape, comment reconstruire l'application sur une machine vierge : versions des composants, variables de configuration, ordre de démarrage. Le test est simple : une personne qui ne connaît pas l'application doit y parvenir seule. Si l'installation passe par un script versionné plutôt qu'un texte, c'est encore mieux, car un script ne ment pas.

2. Le journal des décisions d'architecture

Popularisé par Michael Nygard dans un billet du 15 novembre 2011, le principe est de consigner chaque décision structurante dans une courte fiche : le contexte, la décision, ses conséquences. Une demi-page suffit. Dans deux ans, cette fiche évitera qu'un nouvel intervenant défasse par ignorance un choix qui avait une bonne raison d'être.

3. L'inventaire des accès et des secrets

Qui possède quoi : nom de domaine, hébergement, comptes de service, certificats, licences, boîte d'envoi des notifications. Cet inventaire nomme un responsable côté entreprise pour chaque accès. Les mots de passe eux-mêmes restent dans un coffre dédié, jamais dans le document.

4. Les fiches d'exploitation par incident type

Pour chaque incident déjà rencontré, une fiche d'une page : symptôme visible, première vérification, action corrective, personne à prévenir. Ces fiches, souvent appelées runbooks, transforment une nuit de recherche en dix minutes de procédure. Elles s'écrivent à chaud, juste après l'incident, quand les détails sont encore frais.

5. Le journal des changements

Une liste datée de ce qui a été modifié, par qui et pourquoi, rattachée à chaque livraison. Il permet de remonter à l'origine d'un comportement inattendu et de mesurer le rythme réel de la maintenance, ce qu'un simple devis annuel ne montre jamais.

Où ranger ces documents pour qu'ils restent vrais

La règle qui change tout : la documentation vit avec le code. Rangée dans le même dépôt, en texte simple, elle est relue et versionnée comme le reste, et une modification du code peut être refusée tant que la fiche concernée n'a pas suivi. À l'inverse, un classeur oublié sur un partage réseau se périme en quelques mois, sans que personne ne le remarque.

Ce dépôt doit appartenir à votre entreprise, sur un compte dont vous détenez les droits d'administration. C'est la première question à poser à un prestataire : où est hébergé le code et qui en est propriétaire ? La réponse conditionne toute possibilité de reprise. Pour le cadre contractuel, notre billet sur les clauses d'un contrat de tierce maintenance applicative détaille ce qu'il faut écrire noir sur blanc.

Méthode en cinq étapes pour rattraper le retard

  1. Commencez par la reconstruction. Faites réinstaller l'application sur un environnement vierge par quelqu'un qui n'y a jamais travaillé, et notez chaque blocage. Cette liste est votre plan de documentation.
  2. Inventoriez les accès en une demi-journée. Chaque accès reçoit un nom, un propriétaire et une date de revue.
  3. Rédigez les trois décisions les plus lourdes. Base de données, hébergement, mode d'authentification : ce sont les choix les plus coûteux à défaire.
  4. Écrivez une fiche à chaque incident. Ne cherchez pas l'exhaustivité, le stock se construit au fil de l'eau.
  5. Rejouez la reconstruction une fois par an. C'est ce test qui garde la documentation exacte, comme un test de restauration garde une sauvegarde fiable.

Les erreurs qui rendent la documentation inutile

  • Tout écrire d'un coup. Un document de cent pages, rédigé pendant un projet, n'est jamais relu et se périme dès la livraison suivante.
  • Confier la rédaction à celui qui part. Demandez plutôt à celui qui arrive de lire et de corriger : il voit immédiatement ce qui manque.
  • Documenter le code ligne à ligne. L'utile est ailleurs : le pourquoi, l'exploitation, les accès.
  • Laisser la documentation chez le prestataire. Sans copie dans votre dépôt, elle disparaît avec le contrat.
  • Ne jamais la tester. Une procédure jamais rejouée est une hypothèse, pas une procédure.

Ce que cela change concrètement pour votre entreprise

Une maintenance documentée réduit le temps d'intégration d'un nouvel intervenant, raccourcit les incidents et vous redonne un vrai pouvoir de négociation face à votre prestataire. Elle transforme une dépendance subie en choix assumé : vous restez parce que le service est bon, pas parce que vous n'avez pas le choix. Si vous souhaitez savoir où en est votre application, un premier échange suffit pour faire le point sur ce qui existe et ce qui manque.

Questions fréquentes

Quels documents faut-il exiger d'un prestataire de maintenance logiciel ?

Au minimum un dossier d'installation reproductible, un journal des décisions d'architecture, un inventaire des accès et des secrets, une fiche d'exploitation par incident type et un journal des changements. Ils doivent être livrés dans votre dépôt, pas chez le prestataire.

Combien de temps faut-il pour documenter une application existante ?

Comptez de deux à cinq jours pour un socle utile sur une application de taille moyenne, en commençant par l'installation et les accès. Le reste s'enrichit à chaque intervention plutôt qu'en un grand chantier.

Un code bien écrit dispense-t-il de documentation ?

Non. Le code dit ce que fait l'application, jamais pourquoi un choix a été fait, ni comment la remettre en route après un incident, ni où sont les accès. Ces réponses vivent hors du code.

La documentation est-elle vraiment lue après quelques mois ?

Elle l'est si elle est courte, rangée à côté du code et testée. Une documentation jamais rejouée devient fausse sans que personne ne s'en aperçoive, d'où l'exercice de reconstruction annuel décrit plus haut.

Quelle est la première chose à documenter en cas de doute ?

La procédure de reconstruction de l'environnement à partir de zéro, avec la liste des accès nécessaires. C'est ce qui manque le plus souvent quand la personne qui connaissait l'application quitte l'entreprise.

Parlons de votre projet : nous évaluons avec vous la documentation existante de votre application et ce qu'il faut ajouter pour la rendre transmissible. Pour aller plus loin sur la reprise d'une application vieillissante, consultez notre page reprise et modernisation.