Remerciez-le!

Remerciez @Admin pour avoir partagé cet document gratuitement, de la manière la plus simple, en partageant sur les réseaux sociaux.

Rédaction de documents techniques michel.mainguenaud@insa-rouen.fr 2 Temporalit

Rédaction de documents techniques michel.mainguenaud@insa-rouen.fr 2 Temporalité ●« Avant-vente » – Recherche de financement, réponse à appels d'offre, vanter un savoir faire, … ●Durant l'exécution – Rapports d'avancement, modifications d'objectifs, compte rendu de mission, … ●Livraison – Documentation installation, utilisateur, maintenance, … ●« Après-vente » – Rapports d'activité, d'expertises, ... 3 Cibles ●De l'utilisateur final – Pas forcément expert du domaine – Pas forcément les mêmes implicites – Cultures hétérogènes : langues, lecture, ... ●… au technicien opérationnel – Cible spécialisée dans le domaine – Vocabulaire technique (jargon) ●Evolutions – Versions, rachats d'entreprise, ... 4 Principe ●Document écrit → élément de communication ●Disparition du métier de « dactylo » – Maitrise des outils bureautiques – Travail fait par le cadre (temps masqué ?) – Maitrise des codes de communication ●Tâche importante de la vie de cadre dès le premier niveau de gestion d'équipe – Les rapports de stage sont un premier filtre – Savoir rédiger est une compétence fondamentale d'un ingénieur 5 Contexte ●Normalisation – TC10 : Documentation technique de produits – Documentation informatique : ●ISO/IEC 26513:2009, Ingénierie des systèmes et du logiciel – Exigences pour testeurs et vérificateurs de documentation utilisateur ●ISO/IEC 26511:2011, Ingénierie des systèmes et du logiciel – Exigences pour les gestionnaires de documentation utilisateur ●ISO/IEC 26512:2011, Ingénierie des systèmes et du logiciel – Exigences pour les acheteurs et fournisseurs de documentation utilisateur ●ISO/IEC 26515:2011, Ingénierie des systèmes et du logiciel – Élaboration d’une documentation utilisateur dans un environnement Agile 6 Environnement ●Règles fondamentales : – Plus la cible est haute dans la hiérarchie, moins elle a de temps à consacrer à chaque document ●Doit faciliter la lecture rapide ●Doit être percutant – Vous devez déplacer votre point de vue pour vous adapter à votre cible ●Corollaire – Le document doit être nickel (forme, fond) 7 Environnement (2) ●Questionnement – Quoi (de quoi parle-t-on), qui (la cible), quand (le document sera-t-il lu), pourquoi (causes de la rédaction), pour quoi (finalités), à quel prix (temps, financier, diffusion, …) → Outils adéquats ●Ici (P3) – LaTex, dia (graphique) – Package pour les termes (spécifique Unité P3) – Outils de développement collaboratif (SVN, ...) 8 Environnement (3) ●Globalité – Objectifs du rédacteur ne sont pas forcément ceux du lecteur (notamment pour les problèmes d'IHM) – Les implicites ne sont pas forcément partagés – Style d'écriture (officiel, télégraphique, …) est fonction de la cible – Equipe pluridisciplinaire : technique, communication (charte graphique), ... – Rapport vs. Présentation vs. Flyer, ... 9 Normes pour ASI ●Rôle de la documentation (ISO 9000) – « ...l'élaboration de documents ne représente pas une fin en soi, mais [soit] une activité à valeur ajoutée » – « documents fournissant des informations sur la manière de réaliser des activités et des processus de manière cohérente » 10 Principes généraux d'écriture de documents techniques ●Règle des 4 C : – Correct : pas de fautes de grammaire, syntaxe – Concis : explicitation des sigles, acronymes, … – Concret : style et vocabulaire / cible – Convaincant : plan, structuration logique ●Cible : – Niveau hiérarchique, rapport temps/enjeux – Différence culturelle/domaine (français vs. anglais) 11 Méthode Approach ●A : annonce du sujet ●P : Problématique vis à vis du contexte ●P : Présentation du sujet ●R : Réaction de l'environnement (état de l'art) ●O : Opinions (analyse critique de l'état de l'art) ●A : Actions (votre proposition) ●C : Conclusion vis à vis de la problématique ●H : Horizon (perspectives) 12 Déclinaison ●Introduction – Introduction de la problématique (A) – Présente le contexte général (P) – Présente le problème (P) ●Etat de l'art – Solutions proposées (R) – Analyse critique des solutions proposées (O) ●Solutions proposées – Développement des solutions (A) ●Conclusion – Re-positionnement du problème, solutions apportées (C) – Perspectives (H) 13 Style de rédaction ●Documentation technique : – Pas de faute d'orthographe – Phrases simples (facilite la traduction), peu de « qui, que, ... » – On n'utilise pas de synonyme/unification des termes (exemple : package de l'Unité P3) – Privilégier le même support (LaTex vs. OO) : plus facile pour garantir la cohérence globale 14 Style de rédaction (2) ●Plan – L'introduction finit par une annonce de plan – On ne peut pas avoir de partie 1 sans partie 2 a minima – Toute introduction de chapitre/section doit comporter une annonce de plan – Il ne doit pas y avoir de référence en avant – Tout mot/concept doit être défini avant d'être utilisé 15 Style de rédaction (3) ●Forme – Synthèse après analyse – Un bon dessin vaut mieux qu'un long discours – Architecture documentation électronique ●Liens réactifs (bibliographie, figures, ...) ●Dossiers: figure / document / pdf /…. ●Fontes : éviter les fontes exotiques ●Format du fichier final / utilisateur : collaboratif vs. descendant (pdf) ●Format du fichier intermédiaire : collaboratif (ouvert – OASIS /OpenXML) 16 Style de rédaction (4) ●Forme – Vérifiez qu'il n'y a pas de redite – Un paragraphe développe une seule idée. Tout changement d'idée entraîne un nouveau paragraphe. Un paragraphe commence par une phrase introductive qui résume l’idée – Gardez toujours le même style: ●Liste = lignes constituées de : tiret suivi d'une majuscule, « ; » à la fin, « . » au dernier (par exemple) 17 Style de rédaction (4) ●Toute référence bibliographique doit être référencée en fin de document et toute référence en fin de document doit apparaître dans le texte ●Tout acronyme doit avoir été initialement donné en extension (1 fois par chapitre) + glossaire – Ce Manuel Qualité (MQ) .… ●Assurez vous de la cohérence des informations et références croisées entre documents 18 Style de rédaction (5) ●Bannir le « je » → Nous (le rédacteur + le lecteur) ●Bannir le « on » pronom indéfini → l'acteur ●Respect des conventions typographiques (variables selon les pays) ●Si document long → pied de page avec le titre du document 19 Style de rédaction - Figures (6) ●Couleurs → pensez aux imprimantes N/B ●Usages des cartes – Fréquentes dans les documents – Respect de la sémiologie, citer l'origine ●Toute figure (SVG), tableau, ... doit : – Comporter une numérotation – Comporter une légende – Etre référencée dans le texte – Bannir le « sur la figure suivante ». Il n'y a pas de positionnement pour les figures 20 Style de rédaction - Nombres (7) ●Graphiques avec des axes – label des axes, unités de référence, unités internationales (ISO 80000-1:2009) de préférence ●Veillez au sens des chiffres significatifs dans les nombres (figure et texte) ●Les nombres dans le texte sont en lettre si > 2 ; les valeurs numériques sont groupées par 3 avec un espace/virgule (attention à la ',' en anglais) 21 Style de rédaction - Annexes (7) ●Représentent un niveau de lecture plus approfondi ●Le document doit pouvoir se comprendre sans les annexes ●Ne représentent pas plus de 20 % du texte. ●Doivent être référencées dans le texte 22 Style de rédaction (6) ●Pour faciliter la lecture rapide – Du plus visible au moins visible ●Gras ●Italique ●MAJUSCULE ●Souligné – Titre percutant (évite de lire la partie) – Mise en valeur ●A ne faire qu'après la saisie et la mise en page globale du document 23 Méthode de travail ●Mettez en commun tout ce qui peut être mis en commun (figures, tableaux, ...) – Aide à la lisibilité – Assure la cohérence ●Définissez le plan avant d'écrire – Permet une vision globale – Garantit le respect des niveaux d'abstraction – Permet de prendre du recul vis à vis de la rédaction 24 Méthode de travail (2) ●Travaillez sur le document « papier/pdf » ... surtout si vous n'utilisez pas du WYSIWYG ●Utilisez les outils unix (visu pdf, grep, sed, ...) ●Validez les modifications en deux passes, assurez vous qu'elles ont bien toutes été prises en compte ●Assurez vous que tout est cohérent (notamment pour les informations croisées) ●... Ne sous-estimez pas l'importance du travail de documentation dans un projet 25 Check list - Document ●Numérotation des pages ●Identification – auteurs, institution, version, date, référence ●Titre du document ●Sommaire / Table des matières (pagination) : – Exemple LaTex impose « deux passages » ... ●Liste des acronymes ●Résumé(s) / mot-clés 26 Check list - Rédaction ●Respect de l'annonce du plan (sommaire) ●Respect du lien texte et des figures/tableaux ●Bibliographie croisée (texte vs. Biblio) ●Références internes ●Acronymes ●… et surtout orthographe 27 Finalisation : Signature ●Avez vous la légitimité pour signer ? – Fiche de poste – Délégation de signature ●Quand vous signez un document vous engagez : – Votre responsabilité ●Juridique (attention aux droits d'auteur) ●Morale – Votre image uploads/s1/ documents-techniques.pdf