Documentation technique

1. Objectif du cours

Comprendre ce qu’est une documentation technique, savoir en identifier les types et usages, et maîtriser les méthodes de lecture et de recherche (y compris en anglais) pour être efficace lors d’un projet informatique.

2. Notions et définitions essentielles

• Documentation technique : document référent recensant procédures, processus, méthodologies, étapes et alertes pour l’utilisation/maintenance d’un produit ou service.
• Manuel : document expliquant l’utilisation d’un produit ; peut viser l’utilisateur final ou le personnel technique.
• Fiche technique : document concis décrivant le fonctionnement attendu d’un produit (spécificités techniques).
• MODOP (Mode Opératoire) : procédure détaillée, étape par étape, pour réaliser une tâche.
• Fiche Réflexe (Fiche de Tâche) : document synthétique pour actions rapides en situation d’urgence.
• DEx (Dossier d’Exploitation) : ensemble d’informations pour l’exploitation et la maintenance en production.
• DTArch (Document Technique d’Architecture) : description détaillée de l’architecture d’un système.

3. Fonctionnement et principes

• Rôle : servir de document de référence pour maintenance, support, conformité et transfert de connaissances au client.
• Structuration : une bonne documentation comporte sommaire, sous-titres, introduction, développement des parties, annexes et index ; des visuels (captures, diagrammes, tableaux) facilitent la compréhension.
• Recherche d’informations : d’abord analyser la structure (table des matières) puis cibler les zones pertinentes ; privilégier la lecture complète pour une fiche technique courte, ou une lecture en diagonale pour se repérer avant une recherche ciblée.
• Approche en anglais : sélectionner des mots‑clés en anglais et s’appuyer sur ressources et traducteurs pour accéder aux contenus techniques majoritairement publiés en anglais.

4. Commandes et manipulations

• Recherche par mot-clé dans un document : utiliser le raccourci clavier pour ouvrir un champ de recherche et naviguer parmi les occurrences (procédure présentée comme méthode de recherche dans le cours).
• Démarrer un service sous Windows (exemple opérationnel) : clic droit sur le service → Démarrer (permet de passer l’état du service à « en cours »).
  (Remarque : ces actions sont celles explicitement décrites et illustrées par l’exemple HelpDesk du document.)

5. Sécurité et bonnes pratiques

• Inclure des consignes de sécurité dans les MODOP : règles à respecter pour éviter les risques lors d’une opération.
• Préparer les conditions de relecture : se mettre dans un endroit calme pour être concentré et repérer plus facilement erreurs et incohérences.
• Faire relire par un collègue expert recommandé (non obligatoire) pour détecter ambiguïtés ou imprécisions.
• Utiliser des visuels pertinents (captures, schémas) pour réduire le risque d'erreur d'interprétation.

6. Points essentiels à retenir pour le TSSR

1. La documentation technique est le document de référence d’un projet ; elle recense les informations primordiales.
2. Toujours commencer la consultation par la table des matières pour avoir une vision globale.
3. Choisir la méthode de lecture adaptée : lecture complète pour fiches techniques concises, lecture en diagonale pour repérage initial d’un manuel.
4. Les visuels (captures, diagrammes) sont indispensables pour faciliter la compréhension.
5. En IT, distinguer les documents : MODOP (procédure), Fiche Réflexe (urgence), DEx (exploitation), DTArch (architecture).
6. Sélectionner des mots-clés en anglais est souvent nécessaire ; les ressources en ligne sont essentielles.
7. L’usage de traducteurs (ex. Deepl, Google Traduction) est conseillé si l’anglais n’est pas maîtrisé.
8. Prévoir une relecture et idéalement une relecture par un pair ; l’impression peut aider à annoter.
9. Il est pertinent de produire plusieurs documents pour un même projet selon les besoins (clarté et ciblage).
10. Un MODOP type doit contenir objectif, matériel, prérequis, étapes, critères de réussite et consignes de sécurité.

7. Tableau récapitulatif

Éléments comparés	Objectif principal	Longueur / détail	Usage typique
Manuel	Expliquer l’usage/les procédures	Variable (long)	Utilisateurs ou techniciens
Fiche technique	Décrire fonctionnement technique	Courte (≤ 8 pages)	Spécifications pour devs
MODOP	Procédure pas-à-pas très détaillée	Moyenne à longue	Opérations répétées/sensibles
Fiche Réflexe	Actions rapides en urgence	Très courte	Support/HelpDesk
DEx vs DTArch	Exploitation vs Architecture	DEx = opérationnel, DTArch = conception	Équipes d’exploitation / conception

8. Vérifications pratiques

• Vérifier la présence et la pertinence de la table des matières pour s’assurer de la structuration du document.
• Vérifier qu’une recherche par mot‑clé renvoie des occurrences pertinentes dans le document ou que la barre de recherche de la page web est fonctionnelle.
• Confirmer la présence de visuels (captures, schémas) dans les sections techniques clés.
• Vérifier qu’un manuel comprend bien page de garde (titre, version, dates), sommaire, introduction, annexes et index.
• Exemple opérationnel : après démarrage d’un service (ex. via clic-droit → Démarrer), contrôler que l’état du service indique « en cours » pour pouvoir clôturer le ticket.

9. Flashcards Anki

Quel est l’objectif principal d’une documentation technique ? :: Recenser des informations primordiales
Quand la rédaction technique a-t-elle été officialisée ? :: Lors de la Première Guerre mondiale
Citez trois éléments que recense une documentation technique. :: Procédures, processus, méthodologies
Quels sont les trois types de manuel cités ? :: Manuel procédural, manuel pédagogique, manuel de référence
Qu’est‑ce qu’un MODOP ? :: Un Mode Opératoire décrivant en détail les étapes précises d’une tâche
À quoi sert une fiche réflexe ? :: À décrire rapidement les actions à entreprendre en situation d’urgence
Quelle action permet de rechercher un mot‑clé dans un document selon le cours ? :: Utiliser le raccourci clavier d’ouverture du champ de recherche (recherche par mot‑clé)
Que doit contenir la page de garde d’un manuel ? :: Titre, numéro de version, date de création, date de mise à jour
Pourquoi maîtriser l’anglais en IT selon le cours ? :: Parce que la majorité des éléments techniques et des ressources sont en anglais
Quel traducteur est explicitement recommandé dans les solutions du cours ? :: Deepl