Documentation technique et utilisateur : définition et types de documents

La documentation technique est l'ensemble des documents qui décrivent un système informatique pour ceux qui l'installent, l'exploitent, le dépannent ou le font évoluer ; la documentation utilisateur explique à ceux qui s'en servent comment réaliser leurs tâches. Ce chapitre précise la différence, fait le tour des documents que tu rencontreras (procédure, compte rendu, rapport, notes de version, README…), associe chacun à son lecteur et te donne une méthode pour ne jamais mélanger deux documents en un.

Documentation technique ou documentation utilisateur : la différence

La frontière ne tient pas au sujet, mais au lecteur et à ce qu'il veut faire. Prends une fonction de l'intranet de Sorbier Logistique : un salarié peut ouvrir un ticket d'assistance depuis un formulaire.

Les deux documents parlent du même formulaire. Le premier ne contient aucune adresse IP ; le second ne dit jamais « cliquez sur le gros bouton bleu ». Un document qui essaie de servir les deux lecteurs à la fois ne sert bien ni l'un ni l'autre : le salarié se perd dans les détails techniques, le technicien ne trouve pas ce qu'il cherche entre deux captures.

À chaque lecteur son document

Dans un service informatique, cinq lecteurs reviennent sans cesse. Chacun pose sa question et attend son document.

Un même projet produit donc plusieurs documents. Quand Moussa Diallo met en service le nouveau wiki de Sorbier, il écrit une procédure d'installation (pour Chloé, qui devra peut-être le réinstaller), une fiche d'exploitation (sauvegarde, mises à jour, supervision), une page « Bienvenue sur le wiki » pour les salariés, et un compte rendu pour Antoine, son responsable.

Les familles de documents

Voici les documents que tu croiseras au BTS SIO et en entreprise. Retiens surtout la colonne « lecteur » : c'est elle qui décide du ton et du contenu.

Quatre de ces documents ont un cours qui les détaille : le compte rendu d'intervention et la base de connaissances dans ITIL et support, le cahier de recette dans Tests, le rapport d'incident de sécurité dans Réponse à incident et le PRA dans Sauvegarde et PRA. Ce cours t'apprend ce qu'ils ont en commun : écrire pour un lecteur, structurer, vérifier, maintenir.

Les quatre besoins du lecteur : la méthode Diátaxis

Même pour un seul lecteur, les besoins changent. Un technicien qui arrive chez Sorbier veut d'abord apprendre GLPI ; trois mois plus tard, il veut retrouver vite comment fusionner deux fiches d'ordinateur. Ce ne sont pas les mêmes documents.

La méthode Diátaxis, proposée par Daniele Procida et adoptée par de nombreux projets (dont la documentation d'Ubuntu chez Canonical), range tout document technique dans l'une de quatre catégories, selon deux questions : le texte sert-il à agir ou à comprendre ? Le lecteur est-il en train d'apprendre ou de travailler ?

La règle qui en découle est simple : un document, un type. Une procédure d'installation qui s'arrête tous les trois paragraphes pour raconter l'histoire du protocole devient illisible au moment où l'on en a besoin. Écris l'explication à part et mets un lien vers elle.

Ce que le référentiel du BTS SIO demande

La documentation n'est pas un à-côté : le référentiel du diplôme (arrêté du 29 avril 2019, modifié notamment par l'arrêté du 8 juillet 2024) la cite dans les deux blocs professionnels, donc dans les deux options.

• Bloc 1, commun aux deux options (E5). La personne « rend compte de ses activités afin de constituer une documentation (FAQ, banque de connaissances, etc.) ». Parmi les indicateurs de performance : « le compte rendu d'intervention est clair et explicite », « le projet est documenté », « un rapport de test du service est produit », « un support d'information est disponible » et « la communication écrite et orale est adaptée à l'interlocuteur ».
• Bloc 2 SLAM (E6). Deux compétences sont dédiées : « rédiger des documentations technique et d'utilisation d'une solution applicative » et les « mettre à jour ». Les indicateurs précisent qu'« un document est rédigé pour chaque contexte d'utilisation de l'application et est adapté à chaque destinataire tant par son contenu que par sa présentation », que « les composants logiciels sont documentés de manière à être réutilisés » et qu'« une documentation des versions vient appuyer l'intégration continue ».
• Bloc 2 SISR (E6). La compétence « rédiger ou mettre à jour la documentation technique et utilisateur d'une solution d'infrastructure » a pour indicateurs « la documentation est à jour et disponible » et « une procédure claire de déploiement de la solution est rédigée ». En amont, pour la conception de la solution, un autre indicateur porte sur le choix : « le dossier de choix et l'argumentaire technique sont rédigés et prennent en compte des préoccupations éthiques et environnementales ». Les savoirs associés citent les « techniques de rédaction d'un compte rendu, d'un argumentaire technique, d'une documentation utilisateur et technique, d'une procédure d'installation et de configuration ».

Relis la phrase du bloc SLAM : « adapté à chaque destinataire tant par son contenu que par sa présentation ». C'est exactement la règle « un lecteur, un document » de ce chapitre, écrite dans le texte officiel. Le chapitre 10 détaille ce que la commission vérifie à l'E5 et à l'E6.

Une documentation vivante

Une documentation fausse est pire qu'une documentation absente : le lecteur lui fait confiance, suit une étape périmée et casse quelque chose. Trois habitudes l'empêchent de vieillir en silence.

1. Un en-tête de suivi sur chaque document : version, date de mise à jour, auteur, relecteur, statut (brouillon, validé, obsolète). Un lecteur qui voit « validé le 12/03/2024, version 1.0 » sait qu'il doit vérifier avant de suivre.
2. Une seule source de vérité : une procédure existe à un seul endroit (le wiki, ou le dépôt Git), et les autres lieux pointent vers elle par un lien. Deux copies divergent toujours.
3. La documentation fait partie du travail : une intervention, une évolution ou un changement n'est pas terminé tant que les documents qu'il rend faux ne sont pas corrigés. En développement, on l'ajoute à la « définition de terminé » ; en exploitation, à la checklist de fin de changement (la matrice de mise à jour).

Exercices

Exercice 1 sur 4 Le bon lecteur Réussi À revoir

Pour chaque document, indique son lecteur principal et dis s'il relève de la documentation technique ou utilisateur.

1. « Se connecter au Wi-Fi invité de Sorbier depuis un téléphone. »
2. « Configuration du relais DHCP sur pfSense pour le VLAN 21. »
3. Le fichier README.md du dépôt de l'intranet.
4. « Nouveautés de la version 2.3 de l'intranet : vous pouvez maintenant joindre une photo à un ticket. »
5. Le compte rendu de l'intervention sur le poste PC-0008.
6. La page « Que faire si l'imprimante du 2e étage n'imprime plus ? » de la base de connaissances.

Voir la réponseMasquer la réponse de l'exercice 1

1. Les visiteurs et les salariés : utilisateur.
2. L'administrateur réseau : technique.
3. Le développeur ou l'administrateur qui installe l'intranet : technique.
4. Les salariés qui utilisent l'intranet : utilisateur. Ce sont des notes de version écrites pour eux, dans leur vocabulaire ; le CHANGELOG du dépôt dirait la même chose pour les développeurs.
5. L'équipe du support et le responsable : technique.
6. Cela dépend de la rédaction : écrite pour les salariés (« vérifie que l'imprimante affiche Prête »), c'est de la documentation utilisateur ; écrite pour les techniciens (« purge la file sur le serveur d'impression »), elle est technique. Une base de connaissances contient souvent les deux, avec une visibilité différente : c'est la distinction entre FAQ publique et article interne de GLPI (base de connaissances GLPI).

Tu avais trouvé ?

Oui, j'avais bonPas encore

Exercice 2 sur 4 Quel document écrire ? Réussi À revoir

Dis quel document produire dans chaque situation.

1. Chloé vient de remplacer la carte graphique du poste PC-0001 à la suite d'un ticket.
2. Moussa va migrer le serveur de fichiers un samedi ; Chloé doit pouvoir reprendre s'il est absent.
3. Le serveur de messagerie a été indisponible quatre heures ; la direction veut savoir pourquoi et ce qui est fait pour que ça ne recommence pas.
4. La nouvelle application de réservation des salles sera ouverte lundi à tous les salariés.
5. Tu livres la version 1.3.0 de ton application, qui corrige deux bugs et ajoute un export CSV.
6. Un technicien d'astreinte doit savoir quoi faire si la supervision signale que le pare-feu ne répond plus.

Voir la réponseMasquer la réponse de l'exercice 2

1. Un compte rendu d'intervention, dans le ticket.
2. Une procédure de migration, avec prérequis, étapes vérifiables et retour arrière.
3. Un rapport d'incident : chronologie, impact, cause, correction, mesures préventives.
4. Un guide utilisateur (une page par tâche : réserver, annuler, voir ses réservations) et, idéalement, un court support de prise en main.
5. Une entrée de CHANGELOG (et des notes de version pour les utilisateurs si l'export les concerne).
6. Une fiche réflexe : le symptôme, les vérifications dans l'ordre, quand et à qui escalader.

Tu avais trouvé ?

Oui, j'avais bonPas encore

Exercice 3 sur 4 Classer avec Diátaxis Réussi À revoir

Range chaque document dans l'une des quatre catégories de Diátaxis : tutoriel, guide pratique, référence ou explication.

1. « Les codes de retour de l'API du parc et leur signification. »
2. « Découvrir Git en versionnant ton premier projet, pas à pas. »
3. « Renouveler le certificat du VPN nomade. »
4. « Pourquoi Sorbier sauvegarde selon la règle 3-2-1. »
5. « Le plan d'adressage du siège. »
6. « Créer un compte utilisateur dans l'Active Directory. »

Voir la réponseMasquer la réponse de l'exercice 3

1. Référence : on y cherche une information exacte.
2. Tutoriel : on apprend en faisant, du début à la fin.
3. Guide pratique : un but précis, pour quelqu'un qui sait déjà travailler.
4. Explication : le pourquoi d'un choix.
5. Référence.
6. Guide pratique. Si le document commençait par trois pages sur la structure des annuaires LDAP, il mélangerait guide et explication : ces pages iraient dans un document à part, avec un lien.

Tu avais trouvé ?

Oui, j'avais bonPas encore

Exercice 4 sur 4 Repérer le mélange Réussi À revoir

Voici le début de la page « Installer l'agent de supervision sur un serveur Windows » du wiki de Sorbier :

« Zabbix a été créé en 1998 par Alexei Vladishev. Il existe plusieurs façons de superviser un réseau : par agent, par SNMP, par sondes actives. L'agent 2 est écrit en Go, ce qui permet… (deux pages). Pour installer l'agent, cliquez sur le bouton. »

Quels sont les deux défauts de cette page, et comment la réorganiser ?

Voir la réponseMasquer la réponse de l'exercice 4

1. Elle mélange explication et guide pratique : le technicien qui veut installer l'agent doit lire deux pages d'histoire avant la première action. On déplace l'historique et la comparaison des méthodes dans une page d'explication (« Comment Sorbier supervise ses serveurs ») et on la cite en une ligne en tête du guide.
2. « Cliquez sur le bouton » n'est pas une étape utilisable : quel bouton, dans quel logiciel, sur quel serveur ? Le guide doit donner des étapes numérotées, chacune avec son action précise et le résultat attendu, comme au chapitre 3.

Tu avais trouvé ?

Oui, j'avais bonPas encore