Documentation technique et utilisateur

Questions fréquentes

C'est quoi la documentation technique ?

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 : procédures, schémas réseau, plan d'adressage, fiches serveur, README, documentation d'API, commentaires du code. Elle se distingue de la documentation utilisateur, écrite pour ceux qui se servent du système. Le chapitre Types de documents les classe selon leur lecteur.

Quelle est la différence entre documentation technique et documentation utilisateur ?

La différence tient au lecteur et à ce qu'il veut faire. La documentation utilisateur explique à un salarié, dans son vocabulaire, comment accomplir une tâche (« signaler un problème sur votre poste ») ; la documentation technique explique à un technicien ou à un développeur comment le système est construit et comment l'installer, le réparer ou le modifier. Le référentiel du BTS SIO demande un document « adapté à chaque destinataire tant par son contenu que par sa présentation » : on écrit donc deux documents, pas un seul.

Comment rédiger une procédure informatique ?

Commence par un en-tête (titre avec un verbe, version, date, auteur, relecteur), puis l'objet, les prérequis, l'impact et le point de retour (sauvegarde avant d'agir). Écris ensuite des étapes numérotées, une action par étape, avec les commandes exactes et le résultat attendu, et termine par une vérification finale et un retour arrière. Fais-la suivre par un collègue sans l'aider : chaque hésitation révèle un manque (rédiger une procédure).

Que doit contenir un compte rendu d'intervention ?

Un compte rendu d'intervention répond à six questions : le contexte (qui, quel équipement, depuis quand), le diagnostic (ce que tu as testé et la cause), les actions (avec quel outil, quelle commande), le résultat et sa vérification, la suite à donner et le temps passé. « Réparé » ou « fait le nécessaire » ne sont pas des comptes rendus : un collègue doit pouvoir reprendre ou refaire l'intervention avec ton seul texte. Le référentiel du bloc 1 attend un compte rendu « clair et explicite ».

Comment écrire un bon README ?

Un bon README permet à quelqu'un qui ne connaît pas le projet de le faire tourner en un quart d'heure : description, prérequis avec leurs versions, commandes d'installation, configuration (variables d'environnement, sans aucun secret), lancement, tests, comptes de démonstration et liens vers le reste de la documentation. Garde-le court et déplace l'architecture, l'API et le guide utilisateur dans un dossier docs/ (README et CHANGELOG).

Quel outil utiliser pour la documentation d'une entreprise ?

Pour des procédures et des guides écrits par des techniciens ou lus par des salariés, un wiki comme BookStack ou Wiki.js convient : édition dans le navigateur, recherche, historique, droits par page. Pour la documentation d'une application, le docs as code (Markdown dans le dépôt Git, relu par pull request, publié par un générateur comme Zensical ou Docusaurus) garde la documentation alignée sur le code. Dans les deux cas, une seule source de vérité par document, et jamais de mot de passe dedans (wiki et docs as code).

Comment documenter une API REST ?

Avec un document OpenAPI 3.1, en YAML : chaque route avec ses paramètres, son corps, ses réponses (erreurs comprises), son authentification, des descriptions qui donnent les règles métier et des exemples réalistes. Valide-le avec un linter comme Redocly CLI (npx @redocly/cli lint openapi.yaml) et modifie-le dans la même pull request que le code (documenter une API avec OpenAPI).

Comment faire un schéma réseau ?

Avec draw.io, gratuit, dans le navigateur ou en application : dessine d'abord les zones (un rectangle par VLAN, avec son réseau et sa passerelle), place les équipements dedans avec leur nom et leur adresse, relie-les par des connecteurs, puis ajoute une légende et un cartouche (périmètre, version, date, auteur). Enregistre en .drawio.svg pour garder un fichier modifiable, et vérifie que le schéma dit la même chose que tes configurations (documenter une infrastructure).

Quelle documentation présenter à l'E6 du BTS SIO ?

Le dossier de l'E6 contient, pour chaque réalisation, une fiche descriptive et les éléments constitutifs : ressources utilisées, schémas explicatifs, documentation utile (README, documentation de l'API, CHANGELOG en SLAM ; note de choix, schémas, plan d'adressage, procédures, rapport de tests en SISR). Pendant l'épreuve, l'expression des besoins peut aussi exiger un document précis (rapport de test, documentation technique, rapport d'incident) : prépare des modèles et garde dix minutes pour le rédiger (la documentation à l'E5 et à l'E6).

Faut-il flouter les captures d'écran d'une documentation ?

Le mieux est de ne rien avoir à cacher : fais tes captures sur un environnement de test, avec des données et des comptes fictifs. S'il faut masquer un nom, une adresse ou un secret, utilise un aplat opaque et exporte une nouvelle image, plutôt qu'un flou ou une pixellisation, qui peuvent parfois être déjoués sur du texte. Un secret apparu dans une capture publiée doit être changé (anonymiser une capture).