Chapitre 1015 minDébutant
La documentation à l'E5 et à l'E6 : ce que le jury attend
Par Josselyn C., prof de BTS SIO. Mis à jour le .
À la fin de ce chapitre, tu sauras
- citer les indicateurs du référentiel qui portent sur la documentation ;
- organiser la documentation de tes réalisations pour la commission ;
- produire en dix minutes la documentation demandée à l'E6 ;
- éviter les erreurs qui coûtent des points.
3 exercices corrigés
À l'E5 comme à l'E6 du BTS SIO, la documentation joue deux rôles : elle prouve tes réalisations, puisque la commission les découvre à travers tes documents, et elle est elle-même évaluée, par des indicateurs du référentiel qui portent sur les comptes rendus, les procédures, les rapports de test et la documentation technique et utilisateur. Ce chapitre fait le lien entre ces indicateurs et les documents à préparer, explique comment organiser ta documentation pour la commission, comment produire en une heure la documentation demandée à l'E6, et quelles erreurs éviter.
Ce que dit le référentiel
| Bloc et épreuve | Ce que dit le référentiel | Le document qui le prouve |
|---|---|---|
| Bloc 1, E5 (les deux options) | « Le compte rendu d'intervention est clair et explicite. » | Des comptes rendus réels, issus de tes tickets de stage ou de TP (chapitre 3) |
| Bloc 1, E5 | « Le projet est documenté. » « Un compte rendu clair et concis est réalisé et les écarts sont justifiés. » | Le cahier des charges, le planning, les comptes rendus de réunion (gestion de projet), le bilan (clôture du projet) |
| Bloc 1, E5 | « Un rapport de test du service est produit. » « Un support d'information est disponible. » | Le rapport de test ; le guide utilisateur ou le support de prise en main (mise en service) |
| Bloc 1, E5 | La personne « rend compte de ses activités afin de constituer une documentation (FAQ, banque de connaissances, etc.) » | Des articles de base de connaissances que tu as rédigés (modèle au chapitre 11) |
| Bloc 2 SLAM, E6 | « 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. » | Un README technique, une documentation de l'API, un guide par type d'utilisateur |
| Bloc 2 SLAM, E6 | « Les composants logiciels sont documentés de manière à être réutilisés. » « Une documentation des versions vient appuyer l'intégration continue. » | Les commentaires de documentation du code ; le CHANGELOG et les tags de version |
| Bloc 2 SLAM, E6 | « La documentation technique et d'utilisateurs de la solution applicative sont mises à jour. » | Le CHANGELOG et la documentation modifiés avec l'évolution |
| Bloc 2 SISR, E6 | « Le dossier de choix et l'argumentaire technique sont rédigés et prennent en compte des préoccupations éthiques et environnementales. » | La note de choix : besoin, critères, solutions comparées, recommandation (argumentaire technique) |
| Bloc 2 SISR, E6 | « La documentation est à jour et disponible. » « Une procédure claire de déploiement de la solution est rédigée. » | Les schémas, le plan d'adressage, les procédures de déploiement et d'exploitation |
Ces citations viennent du référentiel du diplôme (arrêté du 29 avril 2019, modifié notamment par l'arrêté du 8 juillet 2024). Deux mots reviennent : adapté (au destinataire) et à jour. Un seul document de 60 pages pour tout le monde, ou une documentation qui ne correspond plus à ce qui tourne, manque les deux.
À l'E5 : des documents qui prouvent tes réalisations
L'E5 s'appuie sur ton dossier numérique : ton portfolio et ton tableau de synthèse (le portfolio de l'E5). La commission y cherche, pour chaque réalisation, la preuve de ce que tu as fait toi-même. Les documents sont ces preuves.
| Ta réalisation | Les documents qui la prouvent |
|---|---|
| Support aux utilisateurs pendant un stage | Deux ou trois comptes rendus d'intervention détaillés, des statistiques de tickets, un article de base de connaissances que tu as écrit |
| Mise en service d'une application | Le cahier de recette et le rapport de test, le guide utilisateur, le support de la séance de prise en main (mise en service) |
| Mise en place d'un service sur ton laboratoire | La procédure d'installation, le schéma, la fiche serveur |
| Projet en équipe | Le planning, les comptes rendus de réunion, la part que tu as rédigée |
Garde à l'esprit que la commission lit en peu de temps. Pour chaque réalisation, une page d'entrée qui liste les documents, avec un lien vers chacun et une phrase qui dit ce qu'il prouve, vaut mieux qu'un dossier compressé de vingt fichiers. Les conseils pour l'oral de l'E5 montrent comment t'en servir pendant la présentation.
À l'E6 : le dossier et la documentation demandée
Le règlement de l'E6 prévoit que ton dossier numérique contienne, pour chacune de tes deux réalisations, une fiche descriptive et « des éléments constitutifs de chaque réalisation professionnelle mise en œuvre par la personne candidate : description des ressources matérielles et logicielles utilisées, schémas explicatifs ou encore documentation utile ». La commission choisit l'une des deux réalisations et rédige une expression des besoins, qui précise « éventuellement la nature de la documentation professionnelle à présenter à l'appui de la solution (rapport de test, documentation technique, rapport d'incident, etc.) ». Après une première phase (30 minutes de préparation, puis 20 minutes d'entretien sur ta démarche), tu as une heure, seul, pour réaliser la solution, avant la recette et l'entretien d'explicitation.
La documentation compte donc deux fois :
- Avant l'épreuve, celle de ton dossier : la commission la lit pour préparer l'expression des besoins. Plus elle est claire, plus la demande portera sur ce que tu maîtrises vraiment.
- Pendant l'épreuve, le document demandé : il fait partie de la production attendue. Une solution qui marche sans le document demandé ne répond qu'à une partie de la demande.
Ce qu'on attend dans le dossier, selon l'option :
| SLAM | SISR |
|---|---|
| README d'installation qui fonctionne sur un poste neuf | Dossier de choix : solutions comparées, critères, solution retenue (argumentaire technique) |
| Documentation de l'API (OpenAPI) | Schémas logique et physique, avant et après |
| Dictionnaire de données (Merise) ou schéma de la base | Plan d'adressage et de nommage |
| Commentaires de documentation sur les classes métier | Configurations commentées (extraits significatifs) |
| CHANGELOG et tags de version | Procédures d'installation, de déploiement et d'exploitation |
| Guide utilisateur par rôle | Cahier de recette et rapport de tests |
| Rapport de test | Documentation utilisateur si le service en a une (connexion au VPN, au Wi-Fi) |
Les cours E6 SLAM et E6 SISR détaillent la fiche descriptive et la composition du dossier de chaque option.
Organiser ta documentation pour la commission
- Une page d'entrée par réalisation : ce qu'elle fait, les documents disponibles avec leurs liens, les comptes de test.
- Une arborescence prévisible, la même pour tes deux réalisations (
01-choix,02-schemas,03-configurations,04-procedures,05-tests, ouREADME,docs/api,docs/guide-utilisateuren SLAM). - Des accès qui marchent : un compte en lecture seule dédié à l'examen sur ton wiki, ton dépôt ou ton outil de supervision, jamais un mot de passe que tu utilises ailleurs. Teste chaque lien depuis une fenêtre de navigation privée, puis depuis un autre réseau.
- Une version et une date sur chaque document.
- Tes propres mots, tes propres captures : une documentation recopiée d'un tutoriel se reconnaît tout de suite (des noms de machines et des adresses qui ne sont pas les tiens, un style qui change d'une page à l'autre). Cite la documentation officielle que tu as utilisée, et écris la procédure de ton environnement, avec tes noms et tes adresses.
- Aucun secret, aucune donnée personnelle réelle : des comptes et des données de test (anonymiser ses captures).
Produire la documentation demandée en une heure
L'expression des besoins t'impose d'écrire vite, sous pression, en même temps que tu réalises. Trois règles :
- Prépare des modèles dans ton dépôt ou ton wiki avant l'épreuve : rapport de test, documentation technique, rapport d'incident, documentation utilisateur (chapitre 11). Le jour J, tu remplis, tu n'inventes pas la structure.
- Tiens un journal pendant l'heure : chaque commande, chaque paramètre, chaque résultat, au moment où tu le fais. Le document final se rédige à partir de ce journal.
- Garde dix à douze minutes à la fin pour rejouer tes tests, faire les captures et rédiger. Ce temps se protège dès le début de l'heure.
| Document demandé | Contenu minimal |
|---|---|
| Rapport de test | Un tableau : exigence, test, résultat attendu, résultat obtenu, statut ; une conclusion |
| Documentation technique | Objet ; ce qui a changé (fichiers, paramètres, routes, tables, schéma) ; comment vérifier ; comment revenir en arrière |
| Rapport d'incident | Symptôme, impact, diagnostic, cause, correction, mesure pour éviter la récidive |
| Documentation utilisateur | Ce que l'utilisateur peut faire de nouveau, étape par étape, avec le message qu'il verra en cas d'erreur |
Un exemple, sur la réalisation « wiki interne » d'une étudiante en SISR. L'expression des besoins demande : « Les membres du groupe GG_Direction doivent pouvoir lire l'étagère Direction du wiki avec leur compte du domaine ; les autres salariés ne doivent pas la voir. Documentation à présenter : documentation technique et rapport de test. » Voici ce qu'elle rédige dans les dix dernières minutes.
Documentation technique : accès de la direction à l'étagère Direction du wiki. Version 1.0, jour de l'épreuve.
Objet. Les membres du groupe Active Directory
GG_Directionlisent l'étagère Direction ; les autres salariés ne la voient pas.Ce qui a changé.
- Fichier
.envde BookStack sursrv-wiki: synchronisation des groupes LDAP activée (LDAP_USER_TO_GROUPS=true,LDAP_GROUP_ATTRIBUTE="memberOf",LDAP_REMOVE_FROM_GROUPS=truepour qu'un salarié retiré du groupe perde l'accès). Copie de l'ancien fichier :.env.avant-direction.- Rôle BookStack Direction créé, champ External Authentication IDs :
gg_direction(BookStack compare les noms de groupes en minuscules).- Permissions de l'étagère Direction : lecture pour le rôle Direction, aucun accès pour les autres rôles ; permissions copiées sur les livres de l'étagère, car celles d'une étagère ne s'appliquent pas toutes seules à ses livres.
Vérification. Rapport de test ci-dessous.
Retour arrière. Remettre
.env.avant-directionà la place de.env; supprimer le rôle Direction ; rétablir les permissions précédentes de l'étagère (lecture pour le service informatique seulement).
N° Test Résultat attendu Résultat obtenu Statut T1 Connexion avec test.direction, membre deGG_DirectionL'étagère Direction et ses livres sont visibles, en lecture seule Visibles, en lecture seule Conforme T2 Connexion avec test.logistique, non membreL'étagère Direction n'apparaît pas, ni dans la recherche Absente, y compris de la recherche Conforme T3 Retrait de test.directiondu groupe, puis nouvelle connexionL'étagère n'est plus visible Plus visible Conforme Conclusion. Les trois tests sont conformes ; T3 prouve que le retrait du groupe retire l'accès.
Ce document tient en une page, mais il coche tout : ce qui a changé et où, comment vérifier, comment annuler, et des tests qui couvrent le cas positif, le cas négatif et le retrait d'un droit.
Les erreurs qui coûtent des points
| Erreur | Ce que voit la commission | Correction |
|---|---|---|
| Documentation copiée d'un tutoriel | Des noms et des adresses qui ne sont pas ceux de ta réalisation | Ta procédure, sur ton environnement, avec la source citée |
| Un document unique pour tous les lecteurs | Ni l'utilisateur ni le technicien ne s'y retrouvent ; l'indicateur « adapté à chaque destinataire » n'est pas atteint | Un document par lecteur (chapitre 1) |
| Schéma sans adresses, ou différent des configurations | La documentation n'est pas « à jour » | Un schéma qui dit la même chose que les configurations |
| Lien mort, dossier privé, mot de passe expiré | La commission ne peut pas évaluer | Tester les accès une semaine avant, depuis un autre réseau |
| Captures avec de vrais noms, de vrais mots de passe | Un manque de rigueur sur la sécurité et le RGPD | Données de test, captures anonymisées |
| Rapport de test sans résultat obtenu, ou avec des tests jamais lancés | Des tests qui ne prouvent rien | Des résultats réels, y compris les non conformes, expliqués |
| Document demandé oublié pendant l'heure | Une production incomplète | Dix minutes réservées et un modèle prêt |
La liste de contrôle, une semaine avant l'épreuve
| Vérification | Oui ? |
|---|---|
| Chaque réalisation a une page d'entrée qui liste ses documents et leurs liens | |
| Chaque lien s'ouvre depuis une fenêtre privée, sur un autre réseau ; le compte d'examen fonctionne | |
| Le README (SLAM) installe le projet sur un poste neuf ; la procédure (SISR) a été suivie sur une VM neuve | |
| Les schémas et le plan d'adressage correspondent aux configurations actuelles | |
| Chaque document porte une version et une date | |
| Aucune capture ne contient de secret ou de donnée personnelle réelle | |
| Les modèles de rapport de test, de documentation technique, de rapport d'incident et de documentation utilisateur sont prêts | |
| Le CHANGELOG (SLAM) ou le journal des changements (SISR) est à jour |
Exercices
Exercice 1 sur 3 Évaluer un extrait de dossier Réussi À revoir
Le dossier E6 d'un étudiant SISR, réalisation « supervision avec Zabbix », contient : une procédure d'installation de 40 pages copiée d'un site de tutoriels, avec des captures d'un serveur nommé zabbix-demo en 10.0.0.5 ; un schéma sans adresses ; un fichier « identifiants.txt » avec le mot de passe administrateur de Zabbix ; aucun rapport de test. Liste les problèmes et ce qu'il doit faire, par ordre de priorité.
Voir la réponseMasquer la réponse de l'exercice 1
- Le fichier « identifiants.txt » : un mot de passe d'administration en clair dans un dossier remis. Le supprimer, changer ce mot de passe, et créer un compte en lecture seule dédié à l'examen, communiqué selon les modalités d'accès de la fiche.
- La procédure copiée : elle ne prouve pas que l'étudiant a fait le travail, et ne décrit pas sa réalisation. La réécrire, courte, pour son serveur (nom, adresse, versions), en citant la documentation officielle utilisée.
- Aucun rapport de test : l'indicateur « le rapport de tests est rédigé » n'est pas couvert. Écrire un tableau de tests : une alerte déclenchée quand un service s'arrête, une notification reçue, un hôte ajouté par découverte, avec les résultats réels.
- Le schéma sans adresses : ajouter réseaux, adresses, noms, cartouche et légende, cohérents avec les configurations (chapitre 9).
Tu avais trouvé ?
Exercice 2 sur 3 Préparer le document demandé Réussi À revoir
Réalisation SLAM « API du parc ». Expression des besoins : « Ajouter un filtre par marque à la liste des postes (GET /postes?marque=Dell). Documentation à présenter : documentation technique. » Liste ce que doit contenir ta documentation technique, en t'appuyant sur les chapitres de ce cours.
Voir la réponseMasquer la réponse de l'exercice 2
- Objet : le filtre par marque sur la liste des postes.
- Ce qui a changé : le paramètre
marqueajouté dans le document OpenAPI (in: query, type chaîne, description qui précise si la comparaison tient compte des majuscules) ; la fonction ou la requête SQL modifiée (nom du fichier) ; le ou les tests ajoutés ; l'entrée Ajouté dans la section Non publié du CHANGELOG. - Comment vérifier : la commande de test, et un appel d'exemple avec son résultat (
GET /postes?marque=Dellrenvoie les postes Dell, et aucun autre). - Comment revenir en arrière : le commit à annuler (
git revert), puisque la base n'a pas changé. - Version : un ajout compatible fera passer l'API de 1.2.0 à 1.3.0 à la prochaine publication (chapitre 5).
Et le document OpenAPI repasse la validation de Redocly CLI (chapitre 8).
Tu avais trouvé ?
Exercice 3 sur 3 Les questions de la commission Réussi À revoir
Prépare une réponse de deux ou trois phrases à chaque question, pour ta propre réalisation, puis compare avec les réponses types.
- « Si vous quittiez l'entreprise demain, comment un collègue reprendrait-il votre travail ? »
- « Pourquoi votre guide utilisateur ne contient-il aucune adresse IP ? »
- « Comment savez-vous que votre documentation est à jour ? »
Voir la réponseMasquer la réponse de l'exercice 3
- « Tout est dans le wiki : la fiche serveur, la procédure de déploiement, qu'un collègue a suivie sur une VM neuve, et la procédure de restauration testée le 8 novembre. Les secrets sont dans le coffre-fort de l'équipe ; la fiche dit dans quelle entrée. »
- « Il est écrit pour les salariés, qui n'en ont pas besoin : il leur dit comment faire leur tâche, avec leur vocabulaire. Les adresses sont dans la documentation technique, écrite pour les techniciens : un document par destinataire. »
- « Chaque changement passe par un ticket qui n'est clos qu'avec la documentation mise à jour, et chaque document porte sa version et sa date. Avant l'épreuve, j'ai comparé le schéma et le plan d'adressage aux configurations. »
Tu avais trouvé ?