transp. - imagine
Contents
1. G nie logiciel D ocumentation 2005 2007 Renaud Marlet Manuel d installation Proc dure d installation Guide dans les choix d installation Fichier ALIRE README Peut tre impl ment dans un wizard G nie logiciel D ocumentation 2005 2007 Renaud Marlet Manuel d introduction tutoriel Introduction p dagogique Utilisation de base Exemples simples Class par rubriques de difficult croissante G nie logiciel Documentation 2005 2007 Renaud Marlet Manuel de l utilisateur user s guide 15 e Description fonctionnelle simple e Illustration par des exemples e Couverture large pas n cessairement exhaustive e G n ralement class par th mes version en ligne avec index G nie logiciel Documentation 2005 2007 Renaud Marlet Manuel de r f rence 16 e Liste exhaustive de chaque fonctionnalit e Description d taill e de toutes les possibilit s e Souvent class par ordre alphab tique ou par ordre alphab tique sous chaque th me version en ligne avec index G nie logiciel Documentation 2005 2007 Renaud Marlet Manuel de maintenance 17 e Proc dures suivre pour Diagnostiquer un probl me e S il se passe XXX alors v rifier YYY R soudre un probl me troubleshooting e S il se passe XXX alors faites YYY Demander de l aide e contact du support email t l formulaire Signaler un bogue bug report e2. Peut faire partie du manuel utilisateur e Peut tre impl ment dans un wizard G nie logiciel Documentation 2005 2007 Renaud Marlet Foire Aux Questions FAQ 18 Frequently Asked Questions e Questions les plus fr quentes techniques ou non e R ponses br ves mais tr s pratiques sans n cessairement expliquer pourquoi a marche e Regroup es par th me G nie logiciel Documentation 2005 2007 Renaud Marlet Carte de r f rence 19 Aide m moire e Sur 1 ou 2 pages souvent cartonn es e Vue tr s sch matique e Principales fonctionnalit s du produit e Chacune en 1 ou 2 lignes e Style t l graphique pas de phrases G nie logiciel Documentation 2005 2007 Renaud Marlet Aide lectronique 1 20 e Aide en ligne th matique proche du manuel de l utilisateur par index proche du manuel de r f rence recherche dynamique par combinaison de mots cl s boutons sp cifiques sur certaines fen tres e Bulles d aide apparition fugace sous la souris Infobulle nom de la fonctionnalit d un bouton Infoballon br ve description de l effet d un bouton G nie logiciel Documentation 2005 2007 Renaud Marlet Aide lectronique 2 21 e Messages d erreur e Assistant activation plus ou moins automatique d tection d une t che pouvant n cessiter assistance e Wizard guide progressif pour effectuer une t che par ex installation con
3. G nie Logiciel d apr s A M Hugues Documentation Renaud Marlet LaBRI INRIA http www labri fr marlet m j 21 03 2007 G nie logiciel Documentation 2005 2007 Renaud Marlet Pourquoi c est important e Documentation interne conception reflet de la vie du projet guide la majeure partie de l activit du projet e Documentation externe manuels contact direct avec le client e bien inform gt efficace satisfait gt revient recommande e bien inform gt vite les demandes de support superflues G nie logiciel Documentation 2005 2007 Renaud Marlet Objectif de cet expos e Sensibiliser e Organiser e Guider Plus g n ral que pour le seul g nie logiciel G nie logiciel Documentation 2005 2007 Renaud Marlet Plan de l expos e Document internes e Documents externes e Format des documents e Difficult s et m thodologie G nie logiciel Documentation 2005 2007 Renaud Marlet Plan de l expos gt Document internes e Documents externes e Format des documents e Difficult s et m thodologie G nie logiciel Documentation 2005 2007 Renaud Marlet Documents internes 1 Documents li s une phase du cycle de vie cahier des charges sp cifications fonctionnelles plan d int gration manuel de conception globale et d taill e proc dure de validation e plan des tests unitaires e plan des tests d int
4. figuration diagnostic e Trucs et astuces tips une br ve information chaque lancement G nie logiciel Documentation 2005 2007 Renaud Marlet Documents commerciaux 22 e Plaquette commerciale e Fact sheet e White paper G nie logiciel D ocumentation 2005 2007 Renaud Marlet Plaquette commerciale 23 e Joli et simple Couleur papier glac 1 feuille 1 ou 2 sch mas synth tiques Beaucoup d adijectifs dithyrambiques G nie logiciel Documentation 2005 2007 Renaud Marlet 24 Fact sheet litt ralement feuille de faits e En gros 1 4 pages e Liste des caract ristiques et capacit s e Quasi exhaustif e Tr s technique gt l attention des utilisateurs experts gt qui feront des recommandations leurs d cideurs G nie logiciel Documentation 2005 2007 Renaud Marlet White paper 25 Un petit article 4 20 pages qui d crit le produit e Argument pose le probl me montre comment le produit le r sout e Souvent un peu technique gt l attention des utilisateurs e Peut tre aussi purement commercial gt l attention des d cideurs G nie logiciel Documentation 2005 2007 Renaud Marlet 2 6 Documentation compl mentaire e Site web du fournisseur annonces mises jour failles d couvertes success stories liste des clients prestigieux forums d assistance fournisseur amp utilisateurs cri
5. gration e plan des tests de validation e plan des tests de non r gression G nie logiciel Documentation 2005 2007 Renaud Marlet Documents internes 2 Documents transversaux la vie du projet glossaire liste des abr viations plan projet plan qualit G nie logiciel Documentation 2005 2007 Renaud Marlet Documents internes 3 Historiques informations de versions et modifications suivi des bugs r sultats des campagnes de test G nie logiciel Documentation 2005 2007 Renaud Marlet Documents internes 4 Documents li s au code commentaires e dans les programmes e sur les donn es XML etc documentation extraite automatiquement du code e javadoc e literate programming G nie logiciel Documentation 2005 2007 Renaud Marlet Plan du cours 10 e Document internes gt Documents externes e Format des documents e Difficult s et m thodologie G nie logiciel Documentation 2005 2007 Renaud Marlet Documents externes client 11 e Documents pour l utilisateur manuels techniques e Documents pour le d cideur documents commerciaux G nie logiciel Documentation 2005 2007 Renaud Marlet Documents pour l utilisateur 12 e Manuel d installation e Manuel d introduction tutoriel e Manuel utilisateur e Manuel de r f rence e Manuel de maintenance e Foire Aux Questions FAQ e Carte de r f rence e Aide lectronique
6. iller la coh rence des documents garder des liens de tra abilit les mettre jour imm diatement
7. ns pr c dentes barres de modifications G nie logiciel Documentation 2005 2007 Renaud Marlet Format du document contenu e S paration des concepts 1 concept par paragraphe e Num rotation des paragraphes gt facilit de r f rence gt tra abilit num ros par ex 1 3 12 4 ou bien identificateurs courts par ex interf fich ouvrir pour certains types de documents trop lourd sinon G nie logiciel Documentation 2005 2007 Renaud Marlet Plan du cours 33 e Document internes e Documents externes e Forme des documents gt Difficult s et m thodologie G nie logiciel Documentation 2005 2007 Renaud Marlet Difficult s de r alisation 34 T che technique pr cision couverture concision clart p dagogie connaissance des probl mes de l utilisateur traductions pour l internationalisation gt t che souvent confi e des sp cialistes G nie logiciel Documentation 2005 2007 Renaud Marlet 3 5 M thodologie R gles de style faire des paragraphes courts quelques phrases faire des phrases courtes une id e par phrase pr f rer les listes aux phrases puces num rotation pas de verbiage utiliser des formes actives pas des formes passives e X fait Y pas Y est fait par X tre pr cis d finir les termes glossaire utiliser les noms d objets plut t que des r f rences num riques ou en
8. plus des r f rences num riques G nie logiciel Documentation 2005 2007 Renaud Marlet Difficult s de maintenance 36 e laboration et mise jour tout au long du projet e R p titions in vitables redondance entre manuels etc dangereuses risques d incoh rence e double tranchant un document est pr cieux quand il est pertinent trompeur quand il est incoh rent erron pas jour gt nombre incalculable de documents pas plus exploitables G nie logiciel Documentation 2005 2007 Renaud Marlet M thodologie 37 e viter les r p titions sauf si elles ont un v ritable apport p dagogique e viter les incoh rences notamment avec le code d s qu on touche l un imm diatement aussi l autre g n ration automatique partir du code des tests e Garder des liens de tra abilit G nie logiciel Documentation 2005 2007 Renaud Marlet 3 8 M thodologie Archiver les diff rentes versions de documents tout comme le code source avec qui ils doivent rester en phase gt syst me de gestion de version CVS G nie logiciel Documentation 2005 2007 Renaud Marlet A retenir 39 e Fixer une nomenclature de documents num ro et version e Fixer un pattern de document page de garde avec type statut version date e G rer l historique de tous les documents utilisation d un syst me de gestion de version e Ve
9. vent Et aussi forums de discussion d entraide entre utilisateurs sites web d utilisateurs articles de presse notes de cours G nie logiciel Documentation 2005 2007 Renaud Marlet Plan du cours 27 e Document internes e Documents externes gt Format des documents e Difficult s et m thodologie G nie logiciel Documentation 2005 2007 Renaud Marlet 2 8 Format des documents Format sp cifi par le plan qualit un en t te un contenu e souvent conforme au manuel qualit de l entreprise G nie logiciel Documentation 2005 2007 Renaud Marlet Format des documents en t te 1 e Nomenclature num rotation unique pour tout le projet ou par classe ou par t che e Version majeure mineure par ex 2 5 Date de cr ation de derni re mise jour Format des documents en t te 2 e Statut du document brouillon incomplet partiel Stable r vis d finitif et approuv e Restrictions sur les lecteurs potentiels confidentiel diffusion restreinte liste explicite groupe individus G nie logiciel Documentation 2005 2007 Renaud Marlet 3 1 Format des documents en t te 3 e Type de document document de travail sp cification conception plan de test administration compte rendu de r union e Mots cl s facilitent la recherche automatique e Historique des modifications table des versio
Download Pdf Manuals
Related Search