Home

version PDF - Processus de rédaction technique

1. 11 http en wikipedia org wiki Adobe_FrameMaker carrereo gmail com Processus de r daction technique 32 Chapitre 4 Format structur DITA XML section section concept t che r f rence CEK restructuration du contenu FrameMaker mise en place de la cha ne DITA FIGURE 4 7 Restructuration du contenu FrameMaker et mise en place de la cha ne DITA XML Ce travail d harmonisation peut se faire en parall le avec la mise jour et la publication du document FrameMaker La qualit de ce document n en sera que meilleure En m me temps que cette r organisation du contenu vous pouvez mettre en place la cha ne compl te de cr ation gestion et publication DITA XML sur un chantillon de votre contenu mise en place des outils r alisation des feuilles de style des diff rents formats de sortie formation des r dacteurs techniques graphistes et traducteurs formation et sensibilisation des autres acteurs de l entreprise Ce n est qu une fois que sa cha ne est fiable et accept e voire attendue par les autres acteurs de l entreprise que le r dacteur technique peut envisager la migration Si vos documents sont disponibles en plusieurs langues vous devez modifier les fichiers FrameMaker et effectuer la migration pour chaque langue Si un projet de traduction dans une nouvelle langue se profile mieux vaut effectuer la migration avant Table de conversion FrameMaker vers DI
2. Vos fichiers de contenu DITA XML ont l extension dita Les noms des r pertoires des versions linguistiques correspondent aux codes de langues support s par Dita Open Toolkit fr_FR ou en_US par exemple Vos fichiers de contenu DITA XML se trouvent dans des sous r pertoires des r pertoires des versions linguistiques par exemple dans fr_FR tasks et fr_FR topics Les valeurs support es pour la dimension des pages PDF sont fr_FR A4 et en_US US letter Ce script peut tre bien entendu facilement adapt ou inspirer un nouveau script carrereo gmail com Processus de r daction technique 52 Chapitre 4 Format structur DITA XML Attention Ce script est fourni sans garantie Avant toute ex cution de ce script effectuez une sauvegarde de l en semble de votre projet DITA XML fichiers de configuration inclus par exemple sous un syst me de gestion de ver sions Assurez vous de pouvoir restaurer facilement le projet dans son int gralit en cas d erreur ou de comportement inattendu Pour utiliser ce script 1 T l chargez le script de g n ration multilingue DITA XML dans le r pertoire contenant le fichier ditamap du projet Dans un terminal placez vous dans ce r pertoire puis entrez chmod x dita2target sh Dans le terminal entrez mkdir out pour cr er le r pertoire qui contiendra les fichiers cibles Entrez dita2target sh lt fichier ditamap
3. 1 Effectuez une sauvegarde de l ensemble de votre projet de documentation DITA XML 2 Ouvrez un terminal et collez la suite de commandes suivante export THAI http www thaiopensource com download export RED http www redaction technique org media cd 5 wget THAI nxml mode 20041004 tar gz amp amp tar xzvf nxml mode 20041004 tar gz 8 amp wget RED nxml mode environmment txt amp amp cp emacs emacs bak amp amp cat emacs sed a gt emacs tmp mv emacs tmp emacs cat nxml mode environmment txt gt gt emacs amp amp rm nxml mode environmment txt Note Si un message vous avertit que le fichier emacs n existe pas collez les commandes suivantes puis recommencez l op ration cd amp amp touch emacs Cette suite de commandes t l charge et d compresse le mode nXML cr e une copie de sauvegarde du fichier emacs emacs bak crit les variables d environnement du mode nXML dans le fichier emacs 3 T l chargez l archive des sch mas RelaxNG pour DITA XML dans le r pertoire racine de votre projet de docu mentation DITA XML 4 Placez vous dans le r pertoire racine de votre projet de documentation DITA XML puis collez la commande suivante tar xzvf rnc tar gz Cette commande cr e un r pertoire rnc de m me niveau que le lt r pertoire de langue gt 5 T l chargez l archive des fichiers schemas x
4. carrereo gmail com Processus de r daction technique 54 Chapitre 4 Format structur DITA XML 4 6 7 DITA Open Toolkit afficher les r f rences crois es dans les PDF Les r f rences crois es sont un l ment important d une documentation technique bien structur e Elles permettent l utilisateur de naviguer facilement dans les briques d information et sont un l ment crucial de l utilisabilit du document final DITA OT les g re tr s bien condition d effectuer quelques r glages Vous avez plac des balises related links correctement format es dans vos fichiers de contenu DITA XML ou mieux une reltable dans votre structure de table des mati res ditamap la reltable permet de d contextualiser votre contenu et donc de mieux le r utiliser Vous lancez votre commande de g n ration du PDF et mauvaise surprise aucune section Voir aussi n appara t dans le fichier cible Vous essayez alors de g n rer une version HTML de votre contenu et l votre section Voir aussi est bien pr sente DITA OT ne supporterait il pas les r f rences crois es dans les PDF Fort heureusement non Par d faut allez savoir pourquoi les r f rences crois es ne sont pas g n r es dans les PDF par DITA OT Pour les afficher attribuez la valeur no la variable disableRelatedLinks du fi chier demo fo build_template xml Si vous utilisez ant il vous faudra galement passer le param tre args fo include rellinks
5. lt cmd gt lt info gt Si vous ne savez pas lire c est le bouton vert lt info gt lt step gt Prendre en compte les contraintes de traduction L unit d information DITA XML la plus petite est le n ud lt ph gt Le r dacteur technique doit cependant veiller ne lui appliquer le m canisme conref que pour une phrase compl te ou un terme qui ne sera jamais traduit par exemple le nom de la soci t ou d un produit De gros probl mes apparaissent sinon lors de la traduction dans d autres langues carrereo gmail com Processus de r daction technique 42 Chapitre 4 Format structur DITA XML conref C conref B conref E conref A FIGURE 4 17 Les phrases se d coupent diff remment selon les langues Exemple Si vous d cidez de pousser la granulom trie au niveau du segment de phrase et que vous d finissez les conref suivants lt ph id click gt Click the lt ph gt lt ph id blue gt blue lt ph gt lt ph id arrow gt arrow lt ph gt Vous pouvez maintenant utiliser le code suivant lt p gt lt ph conref shared dita click gt lt ph conref shared dita blue gt lt ph conref shared dita arrow gt lt p gt pour que soit g n r e la phrase Click the blue arrow Essayons maintenant de cr er une version fran aise de cette phrase Nous traduisons donc les conref comme suit lt ph id click gt Cliquez sur la lt ph gt lt ph id blue gt bleue lt ph gt lt ph i
6. Processus de r daction technique Version 1 5 carrereo gmail com 2011 2015 Olivier Carr re www redaction technique org Publi sous licence Creative Commons BY NC SA 4 0 www creativecommons org licenses by nc sa 4 0 Table des mati res 1 Lib rez vos informations de leurs silos 1 1 1 Int grer la documentation aux processus de d veloppement 1 1 2 Les sources de ce document sont g r es sous Git 2 L3 LFOrMAS SOUTCES pr pas a aa a E ia a e AR o dl de RE See 3 LA Formatsicibles soa ia res a e dE A A A A 3 15 Propos d ce dociment rosarios A Le ad Da eme ei Ne LE 4 2 Documentation technique diminuer les co ts am liorer la satisfaction client 5 2 1 Delar daction la communication techniques sss s soe 4 48466 ous S die dun ie 6 Me bus 5 2 2 Lestrois niveaux de la documentation technique coe ti a e ira anea ke as e sar A 6 2 5 Principe d simplicit KISS 44 us poea eo du a e a a e a a A R sa a ue Es 7 24 FormatsetoOutils s s lt es ser dan 4 RUN done en de de d Ent dou da 4 Re 8 3 R daction technique un processus industriel 9 311 D mon du projet a ea e A A BA AUS Lis A du 9 3 2 Coll cte de IN CIO so 4 4 5 Lee so due A e e vis 10 3 3 Cr atondu Contenu cocaina D NUE L a te 11 34 IFOTMAatiSQUICS ecos L eau EA E AA UN O EME 12 Dr RETENEN mafe a D ET A RAE A AA E AA A DA E 18 3 6 Validationet controle qualit ss pe e 4 8 5 su
7. Ubuntu ou Debian sur une machine physique ou virtuelle avec le mot de passe administrateur connexion Internet 1 T l chargez et d compressez l archive DITA OT export REPO https github com dita ot dita ot wget REPO releases download 2 1 dita ot 2 1 0 tar gz tar xzvf dita ot 2 1 0 tar gz 2 G n rez votre premier PDF cd dita ot 2 1 0 dita f pdf i samples taskbook ditamap F licitations vous avez compil votre premier projet DITA XML Le fichier PDF g n r est out taskbook pdf Vous pouvez maintenant compiler d autres projets en ignorant les tapes 1 et 2 4 6 4 G n rer un PDF avec DITA Open Toolkit Windows Ce didacticiel DITA XML est destin vous guider dans la mise en place et l utilisation de la cha ne de publication DITA OT dans un environnement Windows test sur Windows XP Pr requis Connexion Internet 1 T l chargez Java puis lancez le programme d installation 2 T l chargez DITA Open Toolkit 154 sur le bureau puis d compressez DITA OT1 5 4 full easy_install bin zip 3 S lectionnez Ex cuter dans le menu D marrer collez la commande suivante puis appuyez sur Entr e cmd Un terminal appara t 4 Collez la commande suivante dans le terminal set full1 DITA OT1 5 4 full easy_install_ bin cd Bureau fu11 DITA OT1 5 4 5 Collez la commande suivante startcmd bat Un nouveau terminal appara t 6 Collez la commande suivante dans
8. carrereo gmail com Processus de r daction technique 41 Chapitre 4 Format structur DITA XML lt xml version 1 0 encoding utf 8 gt lt DOCTYPE task PUBLIC OASIS DTD DITA 1 2 Task EN usr share dita ot dtd technicalContent dtd task dtd gt lt task id shared xml lang fr fr gt lt title gt Conref source lt title gt lt taskbody gt lt steps gt lt step gt lt cmd gt Cliquez sur OK lt cmd gt lt step gt lt steps gt lt taskbody gt Il s agit maintenant de placer un ID sur une structure XML afin de pouvoir r utiliser le contenu de cette structure En l occurrence c est une tape unique comprenant une commande unique que vous souhaitez r utiliser Il est alors pr f rable d utiliser la syntaxe suivante lt step gt lt cmd id click ok gt Cliquez sur OK lt cmd gt lt step gt plut t que la suivante lt step id click ok gt lt cmd gt Cliquez sur OK lt cmd gt lt step gt En effet dans le premier cas vous pourrez utiliser le conref m me si le n ud sup rieur lt step gt contient d autres n uds que lt step gt par exemple lt info gt n ud XML FIGURE 4 16 Placement du conref sur le n ud XML de plus haut niveau Dans le 2e cas tout le contenu du n ud lt step gt sera remplac par la valeur du conref source Par exemple dans le cas suivant tout le contenu du n ud sera absent des livrables lt step id click ok gt
9. 47 http www dr qubit org emacs php predictive download carrereo gmail com Processus de r daction technique 57 Chapitre 5 Contact 5 Contact Vous pouvez me contacter via mes profils LinkedIn et Viadeo 1 http fr linkedin com in carrereolivier 2 http fr viadeo com fr profile olivier carrere carrereo gmail com Processus de r daction technique 58
10. EQU SAT N S d amour mourir me font Belle marquise vos beaux yeux La sortie de la commande echo n est pas affich e Ce qui est affich c est la sortie du programme awk dont la sortie de la commande echo soit la d claration d amour de M Jourdain tait l entr e La sortie finale ne correspond cependant pas ce que l on souhaitait Les champs ne correspondent pas trait pour trait des mots Il faudrait donc raffiner la commande awk Il est plus simple de se tourner vers sed sed s lectionne dans des lignes des ensembles de caract res cit s litt ralement ou via des m ta caract res dans des expressions rationnelles ou expressions r guli res Un m ta caract re connu des expressions rationnelles est le signe indiquant en ligne de commande z ro ou un nombre ind fini de caract res comme dans ls srst sed g re galement des r f rences arri res qui affichent l endroit o on le souhaite la valeur correspondant une expression litt rale ou rationnelle trouv e auparavant Heureusement pour nous la d claration d amour de M Jourdain contient exactement neuf mots ce qui correspond au nombre maximal de r f rences arri res possibles echo Belle marquise vos beaux yeux me font mourir d amour sed M s x Nea VeA NGA Ne NGAN VEA AN e x d x 9 8 6 7 1 2 3 4 5 d amour mourir me font Belle marquise vos beaux yeux Nous buttons sur le m me probl
11. Migration de FrameMaker vers DITA XML D ailleurs si pour une raison quelconque votre projet de migration devait s arr ter l les r dacteurs techniques l entre prise et les utilisateurs y auraient d j beaucoup gagn respectivement en facilit de mise jour coh rence et rapidit de publication des nouvelles versions facilit d acc s l information Restructuration du contenu FrameMaker La partie automatis e d une migration de FrameMaker vers DITA XML consiste appliquer une table de conversion entre les styles FrameMaker et les structures DITA XML Un important travail de restructuration du document FrameMaker doit cependant tre effectu en amont restructuration de l information selon les trois cat gories concept t che et r f rence suppression des overrides propri t s de texte appliqu es manuellement et crasant les styles ce genre d h r sie est sinon impossible du moins tr s limit sous un format structur harmonisation et simplification des styles FrameMaker pour les limiter et les faire correspondre aux balises DITA XML qui seront utilis es par exemple un style note_important vers la balise lt note type important gt il faut donc au pr alable analyser le contenu existant et d cider quel ensemble de balises sera utilis parmi les centaines de balises propos es par DITA XML il est en effet fortement d conseill de les utiliser toutes
12. dita 1 dita Y Ko dita 2 dita dita 3 dita FIGURE 4 13 G rer les conref de mani re d centralis e est peu efficace Les conref sont en effet r solus la compilation m me si les fichiers contenant les valeurs sources ne sont pas r f renc s dans le fichier ditamap permettant de g n rer le livrable ce qui veut dire galement que les fichiers contenant les valeurs sources des conref peuvent se trouver dans un r pertoire de niveau sup rieur celui du ditamap 30 http en wikipedia org wiki XInclude 31 http docs oasis open org dita v1 1 0S archspec conref html carrereo gmail com Processus de r daction technique 40 Chapitre 4 Format structur DITA XML shared dita source du conref Pa cible du conref cibles du conref dita 1 dita dita 2 dita FIGURE 4 14 Bonne gestion des conref Les fichiers de contenu r f renc s dans des structures ditamap ne contiennent donc que des conref cibles et un fichier central f d re tous les conref sources il contient ventuellement galement quelques r f rences internes des conref cibles Ce fichier central doit tre de m me type task concept reference etc que les fichiers de contenu ou du moins du type composite qui accepte tous types de structures DITA XML Pour des raisons d organisation je trouve personnellement efficace de cr er un fichier central par type de topic DITA XML et donc de m me type po
13. rer les relations au sein de ce r seau notamment lors des mises jour Plaquette Site web Y BM Magazine R f rentiel Livre d entreprise unique blanc Animation Guide de l utilisateur FIGURE 3 10 R f rentiel unique En pratique il semble que rares sont les entreprises qui ont franchi ce pas Il est vrai que tant que les formats structur s ne seront pas enseign s dans le secondaire il para t utopique de vouloir y convertir tous les acteurs de la soci t surtout si le turn over y est important Voir aussi Git du fichier au contenu page 18 3 6 Validation et contr le qualit Un support de r daction technique doit tre soumis un contr le qualit rigoureux avant d tre communiqu ses diff rentes cibles Le contenu doit tre valid avant livraison Cela para t vident mais cela demande de bien impliquer en amont les per sonnes charg es de la validation Id alement la phase de validation se d roule en parall le de la phase de cr ation plus les modifications interviennent t t moins elles sont co teuses Un outil de gestion de contenu d entreprise tel qu Alfresco peut sembler int ressant afin de mettre en place des workflows sur le papier du moins Dans les faits une telle solution peut s av rer lourde Elle est de plus peu compatible avec certains formats sources bas s sur des documents modulaires et non monolithiques et avec les logiciels de gestion de
14. Git en revanche la cr ation de branche se fait sans duplication de donn es Sur un m me r pertoire local une commande permet de changer de branche Cr er une traduction d une documentation consiste forker soit cr er une branche le document initial Si l on utilise Git se pose alors le choix entre copier le r pertoire de la langue source cr er une branche sur le r pertoire de la langue source La solution de la branche permet en th orie d effectuer du Cherry picking et d appliquer facilement toutes les langues cibles des modifications affectant uniquement le code XML du projet Par exemple une modification de lt image href filter pdf placement break gt en lt image href filter pdf placement break scalefit yes gt de la version anglaise de la documentation peut facilement tre appliqu e aux versions chinoise francaise allemande ou autre si elle a fait l objet d un commit distinct En pratique cependant cette op ration peut s av rer d licate et n tre r ellement utile que si l on doit g rer un grand nombre de diff rentes versions linguistiques En tout cas la solution des branches autorise de telles op rations non celle des r pertoires Elle est cependant plus difficile appr hender et utiliser par l quipe de r daction technique Voir aussi Git du fichier au contenu page 18 3 5 5 Les CMS le workflow en prime mais une fiabilit tester
15. Les CMS ainsi d nomm s pour des raisons purement marketing mais dont la fonction se comprend mieux avec l acro nyme GED syst me de gestion lectronique de documents apportent des notions de workflow et de gestion des liens qui s av rent pr cieuses lorsque l on g re des documents modulaires S ils utilisent des formats monolithiques tels que FrameMaker les r dacteurs techniques peuvent utiliser des CMS tels que SharePoint Alfresco ou consorts pour 1 t l charger sur leur disque dur une copie locale des fichiers partag s 2 effectuer leurs modifications sur la copie locale 3 d poser la copie modifi e sur le d p t central Cette solution est plus satisfaisante que le partage sur un simple serveur de fichiers ne serait ce que parce que la fr quence laquelle les fichiers transitent sur le r seau est bien moindre Il est cependant toujours n cessaire de verrouiller les fichiers en cours de modification ce dont se charge le CMS Originellement destin s aux documents monolithiques de nombreux CMS prennent aujourd hui en compte la modulari sation des documentations techniques Des solutions telles que DocZone ou Componize cette derni re b tie sur Alfresco sont par exemple explicitement destin es g rer des documentations modulaires bas es sur l architecture XML DITA XML Mais comment croire que ces solutions qui sont fr quemment disponibles sous de nouvelles versions marketing oblige sont tou
16. Te fait cette glace bonne saliver petit gar on d envie Te fait la houle forte tanguer vaste oc an d ivresse carrereo gmail com Processus de r daction technique 17 Chapitre 3 R daction technique un processus industriel Et voil En quelques instants sans jamais ouvrir un seul fichier nous appliquons une suite d op rations complexes sur un nombre ind fini de phrases de m me structure Ce qui n est pas possible sous un traitement de texte ou autre outil muni d une interface graphique ou sur des fichiers binaires 3 5 R f rentiel Le contenu est le capital immat riel de la soci t et doit tre prot g comme tel Il peut tre g r dans diff rents r f ren tiels r pertoires mais aussi outils de gestion de contenu d entreprise et logiciels de gestion de versions 3 5 1 Git du fichier au contenu Vous tes habitu manipuler des fichiers Git vous invite penser autrement Avantage vous avez une ma trise beaucoup plus grande de votre contenu Qu est ce qu un fichier Pour vous un contenu image texte feuille de calcul ou autre identifi par un nom Pour votre syst me d exploitation une suite de bits sur le disque dur laquelle sont associ s un nom de fichier et un chemin de r pertoires Si vous souhaitez g rer votre projet en termes de fichiers sous Git vous allez au devant de maintes difficult s Si vous pensez plut t en termes de contenu tout devient beaucoup plus s
17. XML Si votre support final est un document imprim les solutions existent S il s agit d un format lectronique l absence d un index est largement compens e par la fonction de recherche en plein texte 4 6 9 Utiliser PIDE nXML pour DITA XML Le mode nXML propose de valider en temps r el les documents XML DocBook XHTML ou autres Plus la peine de conna tre le sch ma XML par c ur votre diteur de texte vous propose l autocompl tion des balises XML selon le contexte Il ne supporte cependant pas DITA XML par d faut Ce didacticiel vous permettra d utiliser ce mode Emacs pour DITA XML Pr requis Emacs La structure de r pertoires de votre projet de documentation DITA XML doit tre la suivante r pertoire de langue concepts faq reference tasks 43 http docs oasis open org dita v1 0 langspec reltable html 44 Pour des raisons de d contextualisation et pour se donner la possibilit de r utiliser le contenu ailleurs les r f rences crois es ne sont pas plac es dans le corps du texte mais en fin de section dans une rubrique d di e carrereo gmail com Processus de r daction technique 55 Chapitre 4 Format structur DITA XML topics o lt r pertoire de langue gt a la valeur en_US ou fr_FR etc Les instructions de ligne de commande sont con ues pour GNU Linux elles doivent tre adapt es pour tre utilis es dans un autre environnement
18. Y logiciel o S SRI en source de text Y par 1 ogi Ciel Outil ro Pri taire gr aPhique FIGURE 2 2 Un format standard laisse le choix de l outil Si l on r fl chit en termes de formats en revanche il est possible de mettre en place des solutions volutives Un format ouvert tel que OpenDocument ou DITA XML par exemple seul le second tant un format industriel de r daction technique n est pas li un outil donn Il est donc possible de le modifier et de le manipuler l aide de diff rents logiciels Les formats structur s de type DocBook et DITA XML li s un sch ma XSD normalis e peuvent notamment tre facilement g r s de la cr ation la publication l aide de toute une panoplie d outils de l diteur de texte libre la suite logicielle propri taire et graphique 3 http fr wikipedia org wiki OpenDocument carrereo gmail com Processus de r daction technique 8 Chapitre 3 R daction technique un processus industriel 3 R daction technique un processus industriel La r daction technique repose sur des processus rationnels Trop souvent associ e un fort aspect litt raire elle est fr quemment laiss e l improvisation et l inspiration du r dacteur technique Le r dacteur technique comme les autres intervenants de l entreprise doit r pondre ses objectifs de mani re pr visible et reproductible Ce processus repose sur une m th
19. achev Votre historique de commit ressemble alors au sch ma suivant Synopsis Synopsis y Y 0 0 0 0 0 I y I Texte Texte Texte FIGURE 3 7 Historique Git Lorsque vous placerez vos commits sur le d p t central certains commits repr senteront une tape interm diaire de l une des t ches Votre historique et vos branches seront donc plus difficiles exploiter D autant plus que les t ches inachev es alternent Pour en r cup rer une seule il faudra donc choisir soigneusement les commits via la commande git cherry pick Heureusement Git vous permet de r organiser facilement vos commits avant de les partager Lancez la commande git rebase i HEAD 5 pour r organiser les commits de la version en cours aux cinq pr c dentes par exemple carrereo gmail com Processus de r daction technique 19 Chapitre 3 R daction technique un processus industriel Attention La commande rebase est potentiellement destructive veillez sauvegarder votre espace de travail r per toire git compris avant de l ex cuter sous risque de perdre des donn es vous pouvez galement cr er une branche de sauvegarde provisoire Vous pouvez alors r crire l histoire pour proposer vos collaborateurs un commit pour chaque t che r alis e en son entier comme sur le sch ma suivant Texte Synopsis FIGURE 3 8 Historique Git Les commits ont tout d abord t regroup s par type sur la f
20. all comme suit ant Dargs input samples sequence ditamap Doutput dir out Dtranstype pdf2 Dargs fo include rellinks all 4 6 8 Afficher un index dans un PDF mais pas sous DITA Open Toolkit Tout n est pas parfait sous DITA OT le moteur de publication libre DITA XML Vous avez m ticuleusement ins r vos entr es d index dans vos fichiers de contenu DITA XML Vous g n rez une sortie PDF et l index n appara t pas Un message d erreur de la compilation vous indique que h las FOP ne supporte actuellement pas la g n ration des index Face cette situation vous avez quatre solutions attendre que FOP supporte les index sans date de disponibilit ce choix sera difficile faire accepter par votre direction abandonner DITA XML avouez que ce serait dommage de renoncer aux formidables gains de productivit que permet ce format renoncer afficher l index dans le PDF les arguments en faveur d un tel choix ont un certain poids les index sont difficiles maintenir et offre un surplus d utilisabilit discutable dans un document qui ne sera consult que marginalement sous forme imprim e abandonner DITA OT et se tourner vers une solution propri taire les logiciels non open source XMetal par exemple on souvent recours au moteur de publication XEP de RenderX qui lui supporte parfaitement les index Le probl me de l index n est donc pas un obstacle l adoption de DITA
21. bone ah sb Rae DE bath a EE Rue 24 SM ITAQUCTIONT Re PS RER ROUE ait be AND y ico e ere 25 3 8 Format cible cia pis pie es Ru malaise Bo ant Y a a a 27 39 ILIVEAISON ee 444 4 Le HE eA Te A A a SR s 27 4 Format structur DITA XML 28 4 1 Cas concrets d utilisation de DITA XML 29 42 Formats structur s et Non SITUCTUT S esoo te RAR A ONE ee Re EH AS 29 43 Une architecture documentaire tropicomplexe 4 42 4 4 1 5 4 sua is at sa ue see pur 35 4 4 Du document la base documentaire modulaire 35 45 Cas concret documentation de NuFirewall 39 46 Didacticiels DITA XML et XSL FO 4 454 434 uu4 been net 48 5 Contact 58 Chapitre 1 Lib rez vos informations de leurs silos 1 Lib rez vos informations de leurs silos Des solutions souples et fiables lib rent vos informations des silos d information cloisonn s o elles sont emprisonn es et sous exploit es Oubliez MS Word ou FrameMaker pour passer de la maintenance de la documentation la gestion du cycle de vie des projets documentaires modulaires 1 1 Int grer la documentation aux processus de d veloppement La documentation fait partie du logiciel Fournie avec le produit elle doit sortir en m me temps suivre les m mes cycles de vie et faire l objet des m mes processus de production et de contr le qualit Gestion P 5
22. contenu page 18 Utiliser les branches des syst mes de gestion de sources Les syst mes de gestion de sources proposent de cr er des branches d un projet si un moment donn un projet se divise en deux projets incompatibles une branche est cr e partir du projet principal Le r dacteur technique peut ainsi g rer les diff rentes traductions de la documentation technique Le syst me des branches peut servir en th orie g rer les diff rentes traductions d une documentation technique les diff rentes variations d une m me documentation technique En pratique cependant il vaut mieux g rer les d clinaisons d une m me documentation l aide des m canismes de partage de sections et de filtrage de texte conditionnel des outils de documentation 13 M me si Apple a contribu en populariser certains aspects avec son application Time machine carrereo gmail com Processus de r daction technique 22 Chapitre 3 R daction technique un processus industriel D autre part le syst me de gestion des branches est plus ou moins adapt la gestion des traductions selon le gestionnaire de sources que l on utilise La principale diff rence entre les syst mes de gestion de sources Git et Subversion c est leur mani re de g rer les branches Cr er une branche sous Subversion revient dupliquer un r pertoire Les fichiers des deux r pertoires voluent ensuite s par ment Sous
23. d ailleurs tre beaucoup plus simple que sous FrameMaker 4 2 3 Migrer de FrameMaker vers DITA XML Le but de cette proc dure est de migrer son contenu FrameMaker vers DITA XML sans se plonger dans les arcanes des EDD FrameMaker petits projets uniquement g rer la documentation technique au format DITA XML sans utiliser FrameMaker structur Restructurez le contenu et les styles de vos fichiers de contenu FrameMaker selon les concepts DITA XML Cr ez un document FrameMaker vide et importez y tous les styles existants dans les fichiers migrer Appliquez tous les styles disponibles des paragraphes vides du document FrameMaker vide Enregistrez le document FrameMaker vide sous le nom styles fm Ouvrez FrameMaker structur 11 et cr ez un nouveau fichier DITA XML de type topic E E Choisissez StructureTools gt Exporter le catalogue d l ments en tant qu EDD et sauvegardez la nouvelle EDD sous le nom DITA topic edd fm 7 Ouvrez le fichier styles fm puis choisissez Fichier gt Importer les d finitions d l ments et importez les d finitions d l ments partir de DITA topic edd fm 8 R p tez les trois tapes ci dessus pour les autres types de topics DITA XML task reference etc en modifiant les noms de fichiers comme il se doit 9 Ouvrez le fichier styles fm puis choisissez StructureTools gt G n rer le tableau de conversion 10 Modifiez le fichier de conversion et faites corr
24. dita server gt lt uicontrol conref shared dita logs gt lt menucascade gt lt choice gt lt choices gt lt step gt lt step gt lt cmd gt lt menucascade gt lt uicontrol conref shared dita all gt lt uicontrol conref shared dita editfile gt lt menucascade gt lt cmd gt lt info gt lt ul conref shared dita drill down gt lt li gt lt ul gt lt note conref shared dita randomnames gt lt info gt lt step gt lt steps gt lt taskbody gt lt task gt Seul le texte en noir doit tre traduit Traduire ce type de fichier de contenu DITA XML consiste donc traduire uni quement le titre de la section et l int gralit des conref sources Lorsqu il traduit un ensemble d unit s d information plac es en vrac dans un fichier le traducteur manque cependant cruellement de contexte Le cr ateur du contenu initial doit donc lui fournir une assistance constante La m thode la plus efficace consiste faire travailler le traducteur en r gie Avantage suppl mentaire il pourra ainsi interroger non seulement le r dacteur technique mais galement les concepteurs du produit Note Ne croyez pas qu il s agit l d une contrainte sp cifiquement induite par la modularisation pouss e du contenu Pour avoir fait une cole de traduction reposant sur le principe simple mais efficace du triangle du sens le traducteur doit comprendre le texte source pour le reformuler dans le texte ci
25. ger de type Wiki ou Markdown qui combin au g n rateur de documentation Sphinx offre un bon niveau de fonctionnalit s DITA XML DITA XML est une architecture documentaire XML s mantique et modulaire complexe qui offre des gains de productivit importants gr ce une forte r utilisation du contenu DocBook DocBook est un langage de balisage XML s mantique qui offre un rapport fonctionnalit s complexit aujourd hui peu int ressant 1 4 Formats cibles Vous pouvez compiler ce document avec Python Sphinx aux formats PDF EPUB HTML Ces diff rentes versions sont g n r es partir des m mes sources exactement Elles pr sentent cependant de l g res variations mises en uvre par un m canisme de texte conditionnel Par exemple le terme suivant varie selon le format cible Format cible Terme PDF document EPUB livre lectronique HTML site Voir aussi 2 Seule la version reStructuredText partir de laquelle cette version HTML est cr e est maintenue 3 https github com olivier carrere redaction technique org tree master 4 https github com olivier carrere redaction technique org tree DITA_XML 5 https github com olivier carrere redaction technique org tree DocBook carrereo gmail com Processus de r daction technique 3 Chapitre 1 Lib rez vos informations de leurs silos Cr er des documents diff rents partir des m mes sources
26. investir du temps et de l argent dans un CMS Les gains de productivit spectaculaires report s par certaines entreprises suite la mise en place d un CMS DITA XML ont cependant de quoi faire r fl chir Ainsi Epson America a pu r utiliser jusqu 90 du contenu existant sur de nouveaux projets Si Pon opte pour un CMS celui ci doit clairement supporter DITA XML on ne g re pas un jeu de briques d information comme un document monolithique Adieu donc SharePoint ou Alfresco il faut se tourner vers des solutions d di es telles que Componize ou DocZone Quel que soit le choix initial il est possible tout instant de changer de strat gie sans remettre en cause l existant L architecture DITA XML n est en effet li e aucun r f rentiel particulier Rien n interdit donc de commencer g rer ses projets sans CMS puis d avoir recours une telle solution si les b n fices de ce choix deviennent manifestes Voir aussi Git du fichier au contenu page 18 4 5 Cas concret documentation de NuFirewall La documentation de NuFirewall 7 qui a t per ue par la presse comme un point fort du produit 2 a t r alis e sous DITA XML Si je n avais pas utilis un format qui favorise au maximum la r utilisation de l information je n aurais pas autant pu me consacrer l essentiel le contenu 4 5 1 Partager des blocs d information atomiques avec les conref Lorsque le r dacteur te
27. l organisation du r f rentiel Il n y a pas de recette miracle la livraison d informations dans plusieurs langues demande un suivi constant Mais la prise en compte des contraintes en amont et l utilisation d une m thodologie appropri e permettent d am liorer la qualit et de diminuer les co ts et les d lais de livraison des versions multilingues La traduction doit tre int gr e au workflow documentaire Il faut galement faire communiquer avec les traducteurs les diff rents acteurs r dacteurs techniques mais galement ing nieurs experts et concepteurs Si la documentation repose sur un ensemble de modules la traduction peut se faire en parall le de la r daction ce qui r duit les d lais de livraison carrereo gmail com Processus de r daction technique 25 Chapitre 3 R daction technique un processus industriel 4 9 8 4 s Document Validation Livraison Traduction Validation Livraison monolithique globale globale time to market D d 4 Document Validations Livraison modulaire part O LO Validations Livraison partielles time to market D FIGURE 3 11 Parall lisation de la r daction et de la traduction 1 2 processus s rie Traduction processus parall le En ce qui concerne le r f rentiel des fichiers sources vaut il mieux placer les r pertoires de langue en amont ou en aval des r pertoires de projets documentaires Autrement dit vaut il mieux a
28. les fichiers sources a une mise en valeur typographique dont le sens est explicit dans la section Conventions typographiques du document final Un fichier source DITA XML m lange du texte et des balises d limit es par les signes lt et gt Le texte proprement dit est encapsul dans un jeu de balises ouvrantes de type lt balise gt et de balises fermantes de type lt balise gt selon le sch ma lt balise gt texte lt balise gt Tout texte entr hors d une balise ouvrante et fermante est incorrect et produit un fichier non valide 4 4 2 Typologie de haut niveau de l information DITA XML propose au r dacteur technique une typologie de haut niveau qui est une v ritable aide la structuration du contenu S il cr e un nouveau document au format FrameMaker DocBook ou traitement de texte le r dacteur technique se trouve face une page blanche Selon sa rigueur professionnelle l information transmise l utilisateur oscillera entre les deux p les suivants Organisation rationnelle L utilisateur dispose d un acc s s quentiel rapide et ais l information dont il a besoin Magma informatif L utilisateur doit lire int gralement toute une section voire le document en sa totalit pour esp rer trouver des renseignements utiles Lorsqu il cr e un document DITA XML en revanche le r dacteur technique doit d embl e choisir le mod le qui 17 Dans la pratique un sch ma XSD carrereo gmail com P
29. les fils lectriques lt howtoavoid gt lt messagepanel gt 42 http www redaction technique org media dita2target sh carrereo gmail com Processus de r daction technique 53 Chapitre 4 Format structur DITA XML lt messagepanel audience plombiers gt lt typeofhazard gt Danger pour les plombiers lt typeofhazard gt lt consequence gt Risque de noyade lt consequence gt lt howtoavoid gt Ne plongez pas dans la piscine lt howtoavoid gt lt messagepanel gt lt hazardstatement gt lt p gt Tout contenu plac entre balises ne comportant pas de valeur lt i gt audience lt i gt exclue dans un fichier lt i gt ditaval lt i gt est publi dans les documents destin s aux plombiers et aux lectriciens lt p gt lt body gt lt topic gt Ce code contient des balises DITA XML contenant des valeurs audience diff rentes nous allons exclure le contenu d une de ces deux balises lors de la g n ration du fichier cible en utilisant la cl audience Collez le code suivant dans un fichier et enregistrez ce dernier sous le nom de texte conditionnel ditamap dans le r pertoire DITA 0T1 5 4 lt xml version 1 0 encoding utf 8 gt lt DOCTYPE bookmap PUBLIC OASIS DTD DITA BookMap EN usr share dita ot dtd bookmap dtd bookmap dtd gt lt bookmap id texte conditionnel gt lt booktitle gt lt mainbooktitle gt Exemple de texte conditionnel lt mainbooktitle gt lt book
30. me l expression r guli re ne correspond pas un mot mais une suite de caract res ponctuation comprise Il faut alors utiliser la forme lt gt qui correspond un mot tel que ceux dont M Jourdain se sert pour faire de la prose Nous allons utiliser les caract res d chappement barre oblique inverse Y pour que les signes lt et gt ne soient pas interpr t s litt ralement sous certaines consoles mais comme des m ta caract res ayant une fonction sp ciale carrereo gmail com Processus de r daction technique 15 Chapitre 3 R daction technique un processus industriel export p lt x gt MAS AAA MAS AAA MAS AAA MN VAS ANA MASAS MAS AAA MAS AAA Md A lt ASA echo Belle marquise vos beaux AM yeux me font mourir d amour sed s p 9 18 M6 7 M M2 3 M 5 d amour mourir me font Belle marquise vos beaux yeux Nous pourrions galement utiliser la forme alpha qui fait gagner en lisibilit mais perdre en concision export a alpha export n ax ax ax ax ax ax ax ax d ax echo Belle marquise vos beaux yeux me font mourir d amour sed s n 9 18 6 7 1 2 3 4 5 d amour mourir me font Belle marquise vos beaux yeux C est mieux mais nous avons un probl me de capitalisation Nous allons donc utiliser les op rateurs u et l plac s judicieusement Auparavant nous all
31. or die input_array lt INPUT gt close INPUT Sinput_scalar join finput_array substitution Sinput_scalar s lt body gt n x lt body gt ig open OUTPUT gt ARGV 0 or die print OUTPUT input_scalar close OUTPUT Vous pouvez galement modulariser facilement le contenu l aide des ciseaux XML xml_split 5 ou utiliser le module Perl XML Twig ou encore ce one liner Bash pour renommer les fichiers dita d apr s leur titre ack lt title gt dital sed st _ g tr upper lower sed E s x dita mv 1 g sed E s dita x lt title gt x lt title gt dita 1 dita g 4 3 Une architecture documentaire trop complexe DITA XML permet des gains de productivit importants par la r duction du volume source que le r dacteur technique cr e traduit et maintient Ce gain de productivit se fait au prix d une plus grande complexit Si les projets DITA XML sont plus complexes ils sont cependant moins compliqu s que des projets reposant sur des for mats plus traditionnels de type FrameMaker En effet DITA XML est une architecture rationnelle Le r dacteur technique se trouve donc face un comportement pr dictible des outils qu il utilise loin des trucs et astuces destin s contourner les bugs ou les fonctionnements erratiques des outils plus lourds Le tableau suivant pr sente les diff rents niveaux de complexit induits par DITA XML et les s
32. postule que tout objet mat riel ou virtuel construit par l homme est plus fiable et plus facile maintenir et faire voluer si sa complexit est volontairement r duite C est le principe mis en exergue par antiphrase par les Shadocks Pourquoi faire simple quand on peut faire compliqu C est ce principe qui a pr valu la conception des montres Swatch dont le cahier des charges stipulait qu elles devaient embarquer deux fois moins de pi ces que leurs cons urs R sultat des montres moins ch res plus fiables et disponibles en versions sans cesse renouvel es Ce qui a spectaculairement fonctionn pour des montres peut tre appliqu avec le m me succ s la documentation technique Quel que soit le format utilis le r dacteur technique peut tout aussi bien construire un document l gamment architectur qu une usine gaz Avec DITA XML il lui suffit de ne pas centraliser les conref ou de les imbriquer exag r ment Sous FrameMaker c est encore plus simple peu de garde fous tant pos s la multiplication des styles et des overrides peut rapidement rendre ing rable n importe quel document De m me dans la formulation de ses phrases le r dacteur technique doit toujours avoir le principe KISS l esprit Il est facile de construire des phrases alambiqu es qui d notent plus une m compr hension du sujet qu un raffinement de l criture Construire une phrase simple demande un effort de comp
33. pour les masquer dans les fichiers sources Allez vous devoir cr er deux jeux de fichiers sources certains comportant les informations confidentielles les autres non Adieu alors le single sourcing et la r utilisation du contenu qui vous ont fait choisir DITA XML A D Ay sources langue A filtre livrable langue A sans informations ditaval A avec informations P A confidentielles informations C confidentielles langue A conref sources apa sources langue B filtre livrable langue B sans informations ditaval B sans informations confidentielles confidentielles FIGURE 4 20 Masquer des informations confidentielles aux traducteurs En pla ant le contenu confidentiel dans un fichier que vous appelez par exemple confidentiel dita et en pla ant des conref assortis d une cl de filtrage dans le fichier traduire vous avez r solu votre probl me le traducteur ne traduira que le texte non confidentiel et le livrable g n r dans la langue cible ne contiendra pas le texte confidentiel not comme conditionnel et exclu explicitement par le fichier ditaval pass en argument lors de la compilation 4 5 2 Fournir une information cibl e avec le texte conditionnel ditaval Un fichier ditaval reprend le principe des lunettes que vous chaussez pour visualiser un film en 3D le verre gauche masque une moiti de l image le verre droit en masque l autre moiti Mais seul le r dacteur technique dispose de lunett
34. toute l information dont chaque utilisateur a besoin sur tout type de m dia du support d e learning au document PDF ou papier en passant par le site Web DITA XML applique le principe de non redondance des informations propre aux bases de donn es normalis es Cette architecture transpose la documentation technique la r volution introduite dans l industrie par la standardisation si l on peut construire des automobiles de mod les diff rents partir d un ensemble de pi ces identiques de m me le r dacteur technique peut publier des documents diff rents partir d un ensemble de briques d information standardis es 4 1 Cas concrets d utilisation de DITA XML L utilisation quotidienne du format de r daction structur e DITA XML sur des projets multilingues en tant que r dacteur technique m a amen d velopper certaines solutions et astuces que je vous livre ici Tout retour d exp rience est le bienvenu 4 2 Formats structur s et non structur s Les formats structur s favorisent la cr ation de documents minimalistes complets et coh rents Ils permettent au r dacteur technique de se concentrer sur le contenu et d am liorer l exp rience utilisateur et l utilisabilit de la documentation technique Les informations contenues dans un document technique peuvent tre cat goris es selon leur sens Par d faut DITA XML propose trois types de base concept Introduction ou pr sentation d un co
35. versions le projet Componize l se propose cependant de g rer des projets DITA XML sous Alfresco Il reste cependant imp ratif de mettre en place des tapes de validation tout au long du projet Associ s un syst me de gestion de versions les outils de comparaison sont tr s utiles pour valider les mises 16 http www git scm com 17 http www alfresco com fr 18 http www componize com carrereo gmail com Processus de r daction technique 24 Chapitre 3 R daction technique un processus industriel jour Une version tagu e d un projet DITA XML et la version en cours peuvent par exemple tre export es au format RTF puis compar es sous un traitement de texte Cela est bien moins fastidieux qu une relecture compar e Comparer les modules d information directement sous le syst me de gestion de versions n est pas suffisant car ils ne sont que les briques du document final 3 6 1 Workflow de cr ation et validation Un processus de cr ation et de mise jour de la documentation technique qui repose sur la m moire des acteurs humains est peu fiable Un r dacteur technique peut tre fatigu souffrant en cong s oublier des donn es lorsqu il est satur d informations ou avoir quitt la soci t L information entre deux personnes peut galement mal circuler ou tre mal comprise C est pour pallier ces faiblesses que l homme a cr des outils En revanche il est cr atif l
36. DITA XML texte conditionnel page 53 1 5 propos de ce document Ce document est con u et r alis par un r dacteur technique sp cialis dans l informatique Il a parl parle ou parlera un peu beaucoup ou pas du tout des formats des outils et des t ches suivants reStructuredText DITA XML scripts Bash 6 awk sed expressions rationnelles ou expressions r guli res gestion de versions Git Compilation Makefile Ant XSLT Mise en page HTML CSS PDF LaTeX XSL FO Puisqu il traite des processus et des formats de r daction technique son contenu est cependant moins pertinent que son historique et que ses branches Git Voir aussi Git du fichier au contenu page 18 sed modifiez votre texte sans ouvrir vos fichiers page 15 6 https github com olivier carrere redaction technique org tree master scripts 7 https github com olivier carrere redaction technique org commits master Makefile 8 https github com olivier carrere redaction technique org tree master _static carrereo gmail com Processus de r daction technique 4 Chapitre 2 Documentation technique diminuer les co ts am liorer la satisfaction client 2 Documentation technique diminuer les co ts am liorer la satisfaction client La documentation technique c est comme une ampoule une ampoule basse consommation demande un investissement plus
37. TA XML Lorsque les fichiers FrameMaker sont pr ts pour la migration et que la cha ne DITA XML est parfaitement int gr e 13 aux processus techniques et humains de la soci t le r dacteur technique peut appliquer la table de conversion Vous devriez maintenant tre m me d archiver les fichiers FrameMaker puis de basculer totalement vers le format DITA XML 12 http en wikipedia org wiki Adobe_FrameMaker 13 Bien que ce processus doive tre rapide je vous conseille de le faire juste apr s une livraison d une nouvelle version du document pour avoir la marge de temps suffisante avant la livraison suivante des petits ajustements tant toujours n cessaires carrereo gmail com Processus de r daction technique 33 Chapitre 4 Format structur DITA XML section section concept concept t che task r f rence reference FrameMaker table de DITA conversion FIGURE 4 8 Application d une table de conversion de FrameMaker vers DITA XML Appliquez bien s r ce processus un petit jeu de documents qui ne soit pas si possible d une importance critique Apr s ce premier succ s vous pourrez appliquer le processus aux autres jeux de documents Vous pouvez maintenant progressivement modulariser et partager votre contenu dans le nouveau format afin de tirer parti au maximum de DITA XML Vous pouvez pendant cette phase continuer publier de nouvelles versions du document la publication devrait
38. aide en ligne de pages HTML li es ou autre sans aucune perte d information 4 4 5 Les topics modules d information de base DITA XML Les topics 2 sont les plus petites unit s d information autonomes g r es par DITA XML Chaque topic a un titre et un corps de texte Il ne traite que d un seul sujet Il appartient donc au r dacteur technique de se baser sur la modularit propos e par DITA XML pour bien structurer l information Les topics sont s mantiquement typ s Il existe id alement un type de topic par type d information DITA XML propose par d faut des topics adapt s la documentation des logiciels description de concepts et de t ches liste de commandes etc mais de nouveaux types de fopics peuvent tre cr s pour r pondre d autres besoins Les topics sont une des diff rences principales entre DITA XML et DocBook qui ne propose pas de typologie des briques d information Les topics sont g n ralement stock s plat dans des r pertoires divis s par type de topic Ils sont organis s hi rarchique ment dans des fichiers ditamap et peuvent tre partag s entre diff rents documents Les titres des modules ne sont pas affect s d un niveau de titre La structure des modules tant parfaitement homog ne un module peut avoir un niveau 3 dans un document donn et un niveau 1 dans un autre document sans qu il y ait besoin de modifier en quoi que ce soit les topics Les unit s d information
39. atomiques telles que des remarques des paragraphes voire des phrases ou des segments de phrase qui ne peuvent pas tre munis d un titre ne forment pas des topics Elles peuvent tre cependant partag es via le m canisme conref similaire au m canisme Xinclude propos par DocBook 4 4 6 G rer son contenu DITA XML avec ou sans CMS L architecture DITA XML ne propose pas de m canisme de workflow documentaire natif Les workflows sont pourtant un l ment important d un processus efficace de gestion du cycle de vie du contenu 20 http docs oasis open org dita v1 0 archspec topicover html 21 Pas au sens XPath carrereo gmail com Processus de r daction technique 38 Chapitre 4 Format structur DITA XML Les CMS g rent galement les m tadonn es ce qui permet une recherche plus efficace de l information existante et les r troliens 2 La plupart des entreprises sont r ticentes mettre en place des CMS outils d di s aux workflows Elles ont d ailleurs parfois connu des checs de mise en place de telles solutions part le pass De plus l un des grands avantages de DITA XML c est de s int grer directement dans le syst me d information en place Chez les diteurs de logiciels notamment rien de plus facile que de venir se greffer sur le syst me de gestion des sources en place qu il s agisse de Git de Subversion ou de SourceSafe budget quasi nul Raison de plus pour ne pas
40. avec un diteur de texte de type notepad tout ce que l on voit est une suite de sont opaques caract res hi roglyphiques il n est donc la plupart du temps possible de les modifier qu avec un seul logiciel Les formats texte si on les ouvre avec un diteur de texte on voit du texte et des balises il est donc possible de sont transparents les modifier avec diff rents logiciels et de leur appliquer des op rations de traitement par lot en ligne de commande sans m me les ouvrir et d utiliser de puissantes expressions rationnelles 5 http fr wikipedia org wiki Expression_rationnelle carrereo gmail com Processus de r daction technique 14 Chapitre 3 R daction technique un processus industriel 3 4 3 sed modifiez votre texte sans ouvrir vos fichiers Les clones d Unix sont peu utilis s pour g rer la documentation technique Ceci est trange si l on songe la pl thore d outils disponibles sous ces plateformes pour manipuler du texte dans tous les sens Prenons l exemple du dialogue entre entre M Jourdain et son ma tre de philosophie dans le Bourgeois gentilhomme de Moli re MONSIEUR JOURDAIN Je voudrais donc lui mettre dans un billet Belle marquise vos beaux yeux me font mourir d amour mais je voudrais que cela f t mis d une mani re galante que cela f t tourn gentiment MA TRE DE PHILOSOPHIE On les peut mettre premi rement comme
41. ble et non transcrire une suite de mots d une langue l autre et avoir pratiqu la traduction technique durant plusieurs ann es je sais que tout projet de traduction r ussi repose sur une collaboration efficace entre concepteurs r dacteurs et traducteurs Il est galement possible de factoriser ainsi des l ments de structure et non de contenu tels que des en t tes de tableaux Vous pouvez ainsi pr senter des informations de m me type de mani re homog ne moindre co t c est dire sans recourir la sp cialisation 35 http en wikipedia org wiki Darwin_Information_Typing_Architecture Specialization carrereo gmail com Processus de r daction technique 45 Chapitre 4 Format structur DITA XML Prot ger les informations confidentielles Le puissant m canisme conref de DITA XML se pr te d autres applications que la r duction des co ts Par exemple le r dacteur technique peut masquer des informations dans le code source Voici un cas original d utilisation des conref imaginez que vous devez faire traduire un fichier contenant des informations confidentielles qui ne doivent pas figurer dans la version traduite et auxquelles le traducteur ne doit pas avoir acc s une clause de confidentialit interdit aux clients de diffuser 1 information dont ils disposent Comment faire Le filtrage l aide du m canisme ditaval est con u pour exclure des informations des livrables non
42. btenir rapidement des fichiers dont la seule valeur unique est le titre le reste du contenu pourtant unique car il assemble de mani re unique des blocs d information non uniques tant g n r par des conref Exemple lt xml version 1 0 encoding utf 8 gt lt DOCTYPE task PUBLIC OASIS DTD DITA 1 2 Task EN usr share dita ot dtd technicalContent dtd task dtd gt lt task id display trends xml lang fr fr gt lt title gt Afficher les tendances lt title gt lt taskbody gt lt context audience basic gt lt note type restriction audience advanced gt lt ul gt lt li gt 34 http docs oasis open org dita v1 1 0S archspec conref html carrereo gmail com Processus de r daction technique 44 Chapitre 4 Format structur DITA XML lt ph conref shared dita ip control gt lt li gt lt ul gt lt ph conref shared shared dita see user guide audience no user guide gt lt note gt lt context gt lt steps gt lt step gt lt cmd audience basic gt lt menucascade gt lt uicontrol conref shared dita logs gt lt menucascade gt lt cmd gt lt choices audience advanced gt lt choice gt lt ph conref shared dita physical appliance gt lt menucascade gt lt uicontrol conref shared dita logs gt lt menucascade gt lt choice gt lt choice gt lt ph conref shared dita virtual appliance gt lt menucascade gt lt uicontrol conref shared
43. cation technique a pour but de montrer l ad quation d un produit aux besoins de sa cible Elle recourt pour cela diff rents supports plus ou moins adapt s au niveau d expertise de son public et son statut par rapport l entre prise grand public journalistes prospects clients Le r dacteur technique doit adapter son message chaque public Utilisant toutes les ressources de la communication r daction illustrations films animations il prend constamment en compte la dimension marketing Pour augmenter les ventes tout support de communication doit tre un outil marketing Mais peut on tre la fois logique et cr atif C est n cessaire dans les domaines de la composition musicale de l archi tecture et du d veloppement informatique C est galement le cas pour un r dacteur technique Ceci n cessite une tude de l ad quation entre les besoins du public et les moyens de l entreprise une bonne capacit de cr ation et de r daction une gestion de projet rigoureuse un processus industriel de production et de valorisation du contenu Ce document pr sente quelques exemples de supports de communication technique leur int r t marketing leur ad quation au public et les modalit s de leur valorisation Valoriser un contenu signifie produire un contenu de qualit adapt sa cible conserver tout le contenu existant dans ses diff rentes versions r
44. chnique veut r utiliser des blocs d information DITA XML plus petits qu une section il doit les partager au niveau des fichiers de contenu dita et non dans les structures de table des mati res ditamap gr ce au m canisme conref Le principe des conref est simple lorsqu un conref est mentionn au niveau d un n ud XML donn tout le contenu du n ud cible est remplac par le contenu du n ud source TT B ditamap l dita 2 dita 3 dita 1 51 A ditamap FIGURE 4 11 Partage de blocs d information de granulom trie large entre les ditamap 22 Le r dacteur technique peut ainsi voir o un l ment d information est inclus lors de la mise jour de cet l ment il peut alors juger si l l ment modifi sera toujours valable dans les diff rents contextes 23 http www git scm com 24 Il est possible quoiqu un peu complexe de mettre en place des workflows sous Git via des branches 25 http www componize com 26 http www doczone com 27 http linuxfr org news nufirewall le pare feu libre sans prise de t C3 AAte 28 http www linformaticien com tests id 20068 categoryid 48 edenwall nufirewall le pare feu nouvelle generation aspx 29 http docs oasis open org dita v1 1 0S archspec conref html carrereo gmail com Processus de r daction technique 39 Chapitre 4 Format structur DITA XML Une diff rence notable entre le m canisme des conref et le m canisme XML
45. d arrow gt fl che lt ph gt Nous obtenons alors la phrase Cliquez sur la bleue fleche Pour pallier ce probl me il faudrait r organiser l ordre des conref dans le fichier DITA XML traduit ce qui est difficile ment g rable et fait perdre tout l int r t du m canisme Sans compter que des probl mes pires que ce cas d cole peuvent conduire compl tement abandonner dans la langue cible les conref utilis s dans la langue source je n ai pas d exemple concret offrir ayant toujours vit de tomber dans ce genre de travers Imbriquer les conref Pour des raisons de facilit de mise jour et de maintenance du contenu DITA XML le r dacteur technique doit limiter Peffet poup e russe et ne pas trop imbriquer les conref Un seul niveau d imbrication un conref imbriqu dans un autre me semble le seuil au del duquel le contenu peut vite devenir ing rable Dans l exemple ci dessous le conref source see admin guide contient le conref cible admin guide title Exemple lt p id see admin guide gt Pour de plus amples informations voir le lt ph conref shared dita admin quide title gt lt p gt 33 http docs oasis open org dita v1 1 0S archspec conref html carrereo gmail com Processus de r daction technique 43 Chapitre 4 Format structur DITA XML Ce niveau de complexit est g rable Mais si le conref source admin guide title contient lui m me un conref cible le code DITA XML dev
46. des xinclude c est que le n ud source doit tre conforme au sch ma XSD du fichier source et du fichier cible Ce formalisme rigoureux s il s av re moins souple et oblige parfois quelques acrobaties rend les conref beaucoup plus lisibles que les xinclude et favorise leur utilisation shared dita source du conref Pa cible du conref y cibles du conref dita 1 dita dita 2 dita FIGURE 4 12 Partage de blocs d information de granulom trie fine entre les sections DITA XML Centraliser les conref dans un fichier unique Pour favoriser l utilisation des conref au sein d une quipe de r dacteurs techniques et galement pour simplifier la maintenance des conref il s av re tr s efficace de centraliser tous les conref dans un fichier DITA XML d di Il est a priori plus simple pour r utiliser un contenu d un fichier DITA XML existant de pointer vers ce contenu sans l extraire de son contexte d origine Cependant un des grands principes de la r utilisation du contenu est de d contextua liser le contenu Il est donc terme beaucoup plus efficace pour le r dacteur technique d extraire le contenu r utilis de son fichier d origine et de le placer dans un fichier ne contenant que des sources de conref Il est en effet beaucoup plus facile de placer tous les l ments sources dans un r f rentiel unique que de devoir chercher les diff rentes sources dans une multitude de fichiers
47. disponible sp cifications du produit Intranet pages Trac interview du service R amp D manipulation du produit interview du service marketing interview de clients analyse de la concurrence lecture de la presse sp cialis e interview r US collecte de l information analyse des manipulation sources crites du produit FIGURE 3 2 Collecte de l information Les informations doivent tre recoup es pour minimiser le risque de transmettre des informations erron es ou plus jour Le r dacteur technique doit se livrer un v ritable travail d enqu te En se mettant la place de l utilisateur il v rifie chaque information et fait le tri entre les donn es pertinentes et celles qui ne seront que du bruit perturbant le message Premier utilisateur des solutions d velopp es par la soci t le r dacteur technique a le r le du candide qui remet chaque aspect de l information transmettre dans son contexte Il peut par exemple d cider contre l avis de la direction technique de passer sous silence des informations tr s techniques dans le guide de l utilisateur Inversement il pourra tayer une brochure commerciale de donn es techniques pr cises pour tayer le discours marketing 3 2 1 Tester les produits pour les documenter Le r dacteur technique ne peut fournir une documentation utile aux clients de l entreprise s il se contente de mettre en forme des info
48. dopter la structure suivante english produit 1 produit 2 francais produit 1 produit 2 ou la suivante produit 1 english francais produit 2 english francais Dans la plupart des cas il est pr f rable de placer la distinction entre les langues le plus en amont possible Pour reprendre une terminologie utilis e dans le d veloppement logiciel cr er une traduction d un ensemble d informations quivaut cr er une branche de cet ensemble Comme il est plus facile de manipuler une branche par sa racine que par ses ramifications l usage il est beaucoup plus facile de manipuler des r pertoires complets ne serait ce que pour les fournir aux traducteurs qu un ensemble de sous r pertoires Une fois la traduction r alis e les modifications apport es la version source ou la version traduite ne peuvent tre appliqu es automatiquement l autre version Pour continuer dans la terminologie du monde logiciel la nouvelle branche est un fork il devient impossible d appliquer automatiquement l une les modifications apport es l autre Pour fournir les m mes informations dans les diff rentes langues il est donc crucial de suivre efficacement les mises jour de la version d origine carrereo gmail com Processus de r daction technique 26 Chapitre 3 R daction technique un processus industriel 3 8 Format cible Le format cible d un supp
49. e d veloppeur 224 X Branche D p t secondaire cr partir de la version principale du code source Tag Instantan du tronc ou d une branche un instant t Permet de figer facilement une version par exemple la version publi e et de cr er une archive Si l on s en donne la peine il est galement possible de mal utiliser les syst mes de gestion de version et de perdre des donn es Mais en pratique m me niveau d effort et de comp tence le risque de perdre de donn es est nettement moindre si le r dacteur technique manipule des fichiers texte sous un gestionnaire de version plut t que des fichiers binaires sur un r pertoire partag Les syst mes de gestion de code source ont une fiabilit prouv e et g rent des millions de lignes de code Tout comme les syst mes de fichiers Ext4 Btrfs etc ils voluent lentement selon une politique conservatrice et ne sont propos s en production que lorsqu ils ont t exhaustivement d bogu s Si les plus grands projets de d veloppement informatique tel que GNU Linux par exemple leur font confiance pourquoi ne pas galement leur confier la documentation technique Un b mol cependant ces outils ne sont pas destin s sp cifiquement au format XML et effectuent des comparaisons ligne par ligne entre les fichiers et non pas n ud par n ud ce qui multiplie inutilement les conflits entre les commits ou les branches Voir aussi Git du fichier au
50. e et dans le temps depuis le dernier d p t du fichier sur le r f rentiel et en termes de quantit de travail 6 http rsync samba org 7 http www cis upenn edu bcpierce unison 8 http www microsoft com en us download details aspx id 15155 9 http www git scm com 10 En cas d incident r seau l utilisateur est averti que la transaction destin e placer le fichier modifi sur le d p t a chou il peut alors proc der une nouvelle transaction sa copie locale du fichier tant intacte 11 Surtout sous Git con u explicitement dans ce but 12 Les syst mes de gestion de version favorisent un d p t fr quent de modifications atomiques carrereo gmail com Processus de r daction technique 21 Chapitre 3 R daction technique un processus industriel document FIGURE 3 9 Le syst me de gestion de versions conserve l historique des modifications modifications Des interfaces graphiques permettent d utiliser directement sous les gestionnaires de fichiers ces outils originellement con us pour tre utilis s en ligne de commande Cependant le paradigme sur lequel ils reposent est parfois difficile appr hender pour les publics les moins technophiles Les syst mes de gestion des sources utilisent les concepts suivants Tronc D p t principal conservant toutes les versions des fichiers plac es au cours du temps par le r dacteur technique ou plus fr quemment l
51. e le fichier source et le fichier cible Ce qui semble a priori la solution la plus simple s av re cependant peu efficace en termes de productivit de l quipe de r daction technique et de structuration de l information Avec un format texte tel que DITA XML le r dacteur technique et le lecteur disposent de supports largement diff rents R dacteur technique Le r dacteur technique manipule des fichiers sources il utilise les balises pour construire le document en marquant les l ments d information qu il cr e ou r utilise Les balises sont imbriqu es comme des poup es russes organis es selon une syntaxe rigoureuse Le fichier source n est pas au format WYSIWYG la mise en page sera appliqu e lors de la transformation des fichiers sources en fichiers cibles autrement dit lors de la g n ration des livrables Tout au plus certains logiciels graphiques tels XMetal Oxygen ou FrameMaker structur proposent ils le format WYSIWYM what you see is what you mean o les balises sont remplac es l cran par une mise en forme g n rique diff rente de l aspect final du document Je trouve cependant que l un des int r ts d avoir recours un langage balises est de voir exactement ce que l on fait en manipulant soi m me les balises sans en d l guer l interpr tation un logiciel graphique Utilisateur Seul le contenu est pr sent au lecteur dans le fichier cible le texte marqu par des balises dans
52. e r daction technique est cr dans un format source diff rent du format des livrables le format cible Pour reprendre une image fr quemment utilis e en d veloppement logiciel le format source est la recette de cuisine le format cible le plat En photographie le format source est le format RAW qui est g n r par l appareil photo et sur lequel les photographes professionnels pr f reront apporter les retouches et le format cible le format JPEG Les traitements de texte nous ont d shabitu s distinguer le fond de la forme Mais confondre les deux entra ne beaucoup d erreurs et de perte de temps En effet le document pr sent l utilisateur pr sente deux aspects fondamentaux le contenu la mise en page Au cours du d veloppement d une documentation technique ces deux aspects doivent tre clairement distincts Ils peuvent tre pris en charge par deux intervenants diff rents le r dacteur technique le graphiste Lorsque la mise en page a une importance quivalente celle du contenu ou lorsqu elle doit tre vari e comme dans le cas d une brochure commerciale la r daction et la mise en page s op rent sous des outils diff rents diteur de texte logiciel de PAO par exemple InDesign ou Scribus Lorsque la mise en page a une importance moindre que celle du contenu ou lorsqu elle doit tre homog ne comme dans le cas d une documentation technique la r dacti
53. ens d crire le r dacteur technique doit donc l appr hender par lui m me et se faire sa propre opinion qu il pourra ensuite confronter celle des autres acteurs de l entreprise Le r dacteur technique est un pragmatique qui s int resse la pratique non la th orie S il ne consulte que les d veloppeurs par exemple il aura peu de chance de pouvoir cr er une documentation satisfaisante pour l utilisateur d une part les d veloppeurs ont souvent une vision id aliste du fonctionnement de leur produit diff rente du comportement de ce dernier en conditions r elles d utilisation d autre part une d perdition d information se produit n cessairement entre ce que le d veloppeur sait ce que le d veloppeur exprime ce que le r dacteur technique comprend ce que le r dacteur technique r dige ce que l utilisateur comprend Si le r dacteur technique teste r ellement le comportement du produit dans des conditions aussi proches que possible de celles rencontr es par l utilisateur les trois premi res causes de d perdition d information sont quasiment inexistantes Pour r duire les deux derni res il ne lui reste plus qu filtrer organiser et exprimer l information qu il a recueillie de mani re adapt e au m dia qui la v hiculera et aux connaissances techniques de son destinataire Dans les faits une telle demande peut sembler de prime abord incongrue en interne et se
54. er une nouvelle balise entrez lt puis appuyez sur Ctrl Entr e La liste des balises possibles appara t 8 S lectionnez une balise puis appuyez sur Entr e Appuyez sur Ctrl Entr e pour afficher la liste des attributs autoris s 9 Pour ins rer une balise fermante apr s du texte entrez lt puis appuyez sur Ctrl Entr e 4 6 10 Acc l rer sa saisie avec le mode Predictive pour Emacs Ce didacticiel mode Predictive pour Emacs est destin vous guider dans la mise en place et l utilisation du mode Emacs d aide la r daction et d autocompl tion des mots anglais et fran ais Predictive dans un environnement GNU Linux en l occurrence Debian 1 Installez make et texinfo sudo aptitude install make texinfo 2 T l chargez Predictive 7 3 D compressez l archive Predictive tar xzvf predictive 0 23 13 tar gz 4 Placez vous dans le r pertoire predictive cd predictive 5 Compilez predictive make 6 Installez predictive sudo make install 7 Ins rez le code suivant dans le fichier emacs predictive install location add to list load path emacs d predictive 2 dictionary locations add to list load path emacs d predictive latex add to list load path emacs d predictive texinfo add to list load path emacs d predictive html load predictive package require predictive 8 Lancez Emacs puis appuyez sur Alt X et entrez predictive mode
55. es 3D et a une vision compl te de l information contenue dans le projet DITA XML Les destinataires de l information disposent de lunettes avec deux verres gauches ou deux verres droits Ils ne voient donc qu une partie de l information Loin d tre l s s par cet tat de fait ils ont ainsi un meilleur acc s l information 36 http docs oasis open org dita v1 1 0S archspec conref html 37 http docs oasis open org dita v1 2 0s spec common about ditaval html carrereo gmail com Processus de r daction technique 46 Chapitre 4 Format structur DITA XML Le profilage r alis masque chaque public les informations dont ils n ont pas besoin et qui ne seraient pour eux que du bruit Chaque audience b n ficie donc d un meilleur acc s l information qui la concerne selon le fameux concept minimaliste de less is more ditaval Y source cible 2 FIGURE 4 21 Texte conditionnel avec DITA XML Concr tement le m canisme ditaval est bas sur des op rateurs binaires vous marquez un bloc d information avec un attribut et une valeur puis incluez ou excluez ce bloc dans le livrable en passant un op rande lors de la compilation le bloc est inclus par d faut si aucun op rande n est sp cifi C est le principe du texte conditionnel G ce ce m canisme il n est pas n cessaire de cr er deux fichiers diff rents lorsque leur contenu ne comporte que des variations mi
56. es co ts aidant le d bat a t tranch en faveur du single sourcing Le gain qualitatif discutable ne compense pas le co t de cr er maintenir et traduire une version source diff rente pour chaque version Cible 18 DITA XML propose trois types d information de base tandis que la m thode Information Mapping en propose sept 19 S il s av re qu il a r ellement besoin d une autre cat gorie il peut la cr er via une sp cialisation carrereo gmail com Processus de r daction technique 37 Chapitre 4 Format structur DITA XML PDF LU Site Web FIGURE 4 10 Un seul jeu d informations une multiplicit de formats de sortie Si le r dacteur technique pratique le single sourcing il doit cependant s lectionner en d but de projet le paradigme sur lequel il se base le livre ou l aide en ligne Pendant longtemps les outils propos s reposaient soit sur un document de type livre MS Word ou FrameMaker essentiellement qui pouvait tre export au format d aide en ligne soit sur un fichier source RTF d aide Windows pour g n rer un PDF Une forte perte d information de navigation index r f rences crois es liens etc intervenait souvent lors de l exportation DITA XML propose un mod le agnostique quant au format cible Les fichiers sources bien que bas s sur un mod le modulaire proche de celui de l aide en ligne peuvent facilement tre export s sous forme de fichier PDF d
57. espondre chaque style FrameMaker une balise DITA XML 11 Enregistrez le tableau de conversion sous le nom DITA2FM conversion table fm 12 Ouvrez un fichier de contenu FrameMaker sous FrameMaker structur 11 et choisissez StructureTools gt Utili taires gt Structurer le document en cours 13 S lectionnez DITA2FM conversion table fm et cliquez sur Ajouter structure 14 Enregistrez le fichier de contenu FrameMaker au format XML sans s lectionner d application 15 Ouvrez le fichier XML g n r sous un diteur DITA XML et corrigez la syntaxe DITA XML Certains aspects de cette tape sont scriptables mais il faut galement proc der des op rations manuelles de restructuration du contenu Il vous faudra notamment placer la main les r f rences crois es de pr f rence dans une reltable 14 T appelle jeu de documents tout ensemble d informations li es qui ne partage aucun contenu avec un autre ensemble si par exemple le document A partage une section avec le document B le jeu de documents est A B si vous dupliquez la section partag e afin qu elle ne soit plus commune A et B A et B deviennent des jeux distincts carrereo gmail com Processus de r daction technique 34 Chapitre 4 Format structur DITA XML Pour g n rer les l ments permettant de construire un fichier ditamap vous pouvez par exemple utiliser des scripts Perl du type usr bin perl open INPUT lt ARGV 0
58. ffectuer sous ce CMS Content Manage ment System des modifications transverses ou d avoir un suivi pr cis du cycle de vie du contenu a entra n une migration vers le format de balisage l ger reStructuredText Plateformes de gestion du cycle de vie de la documentation PDF HTML ePUB etc CSS LaTeX Inkscape Emacs Make Bash sed Python Sphynx reStructuredText Git Bugzilla Open source Partiellement open source Toutes les versions de ce document sont g r es sous le logiciel de gestion de versions d centralis Git Les modifications de contenu de structure ou de mise en page peuvent d sormais tre regroup es par lots coh rents li es un ticket de logiciel de suivi de probl mes tel que Bugzilla ou Trac 1 http www git scm com carrereo gmail com Processus de r daction technique 2 Chapitre 1 Lib rez vos informations de leurs silos valid es par des pairs partag es entre diff rentes versions du projet de documentation annul es en une seule op ration etc 1 3 Formats sources Ce document est disponible en trois formats bas s sur la version 1 1 Ces formats pr sentent des niveaux de fonction nalit s et de complexit diff rents fonctionnalit s complexit reStructuredText DocBook FIGURE 1 2 Niveau de fonctionnalit s et de complexit des formats texte reStructuredText reStructuredText est un langage de balisage l
59. ficher tout son contenu exception du titre situ entre les balises lt title gt Vous pouvez recourir alors la syntaxe suivante lt xsl template match x contains class topic example gt lt fo block gt lt xsl apply templates select x not name title gt lt fo block gt lt xsl template gt Cette commande s lectionne tous les n uds enfants du n ud lt example gt l exception du n ud lt title gt Cependant le n ud lt example gt accepte le texte entr directement sans tre encapsul dans des balises Cette commande ne fera alors pas appara tre ce contenu Supposons que le code source d un de vos fichiers DITA XML soit le suivant carrereo gmail com Processus de r daction technique 48 Chapitre 4 Format structur DITA XML lt example gt lt title gt XSL FO lt title gt Voici mon exemple de chemin XPATH lt codeblock gt ancestor or self lt codeblock gt Texte non encapsul situ apr s un n ud enfant lt example gt Le fichier PDF affichera l exemple structur comme suit ancestor or selt Le titre de l exemple n est pas affich ce qui correspond au r sultat souhait mais le contenu non encapsul dans des balises n appara t pas ce qui est un effet de bord ind sirable Pour s lectionner ce contenu il faut s lectionner les n uds textuels avec la syntaxe text Il est alors tentant d utiliser la syntaxe suivante lt xsl temp
60. gt lt nom du r pertoire de langue gt lt format cible gt pour g n rer les fichiers cibles L argument format cible accepte les valeurs g r es par DITA OT Exemple dita2target sh firewall ditamap en_US pdf2 Le fichier PDF firewall pdf est alors g n r dans le r pertoire out sp cifi en dur dans le script 4 6 6 Cr er des documents diff rents partir des m mes sources DITA XML texte conditionnel DITA XML offre un m canisme de texte conditionnel Ce m canisme favorise la r utilisation du contenu source et vite la redondance des informations Ce didacticiel aidera le r dacteur technique utiliser ce m canisme en quelques minutes Pr requis Vous avez install DITA OT dans le r pertoire DITA OT1 5 4 sous GNU Linux ou Windows 1 Collez le code suivant dans un fichier et enregistrez ce dernier sous le nom de texte conditionnel dita dans le r pertoire DITA 0T1 5 4 lt xml version 1 0 encoding utf 8 gt lt DOCTYPE topic PUBLIC OASIS DTD DITA 1 2 Topic EN usr share dita ot dtd technicalContent dtd topic dtd gt lt topic id exemple topic xml lang fr fr gt lt title gt Utilisation du texte conditionnel lt title gt lt body gt lt hazardstatement gt lt messagepanel audience electriciens gt lt typeofhazard gt Danger pour les lectriciens lt typeofhazard gt lt consequence gt Risque d lectrocution lt consequence gt lt howtoavoid gt Ne touchez pas
61. heurter la lourdeur de la mise en place d une plateforme de test Ce n est g n ralement qu apr s les premiers retours clients ou les tests produits dans la presse que les diff rents interlocuteurs comprennent pleinement l apport de cette d marche C est souvent seulement partir de ce moment l que la r daction technique gagne ses lettres de noblesse Et que la documentation technique n est plus seulement vue comme un mal n cessaire mais comme une v ritable valeur ajout e 3 3 Cr ation du contenu Le r dacteur technique cr e le contenu du projet de r daction technique dans un dialogue constant avec les diff rents acteurs de la soci t services R amp D marketing Il prend en compte en amont les diff rentes contraintes li es au cycle de vie des supports de r daction technique En particulier le r dacteur technique a soin de faire valider le contenu ses interlocuteurs afin d apporter les modifications n cessaires aussi t t que possible ceci garantit que le r sultat sera conforme au projet initialement d fini carrereo gmail com Processus de r daction technique 11 Chapitre 3 R daction technique un processus industriel minimiser le volume de texte et d images sources afin de r duire les co ts de production de maintenance et de traduction prendre en compte d s le d but du projet les contraintes d internationalisation 3 4 Format source Le contenu d un projet d
62. i vous faites une erreur vous ne pourrez pas retrouver le statu quo ante de vos fichiers en revenant la branche master Si vous voulez enregistrer votre travail au fil de l eau afin de pouvoir revenir tout moment un tat ant rieur il vous faut donc committer r guli rement et sauvegarder votre espace de travail r pertoire git y compris par exemple via rsync Lorsque vous d ciderez de partager votre travail vous pourrez d placer fusionner ou supprimer vos commits avant de les envoyer sous forme de patchs ou de les d poser sur un d p t central Faire sauter les goulets d tranglement avec les branches Les branches Gif permettent de facilement effectuer en parall le plusieurs t ches non li es Imaginons le sc nario de travail suivant On vous demande de migrer une section d un document un autre Vous envoyez votre proposition pour validation La validation se fait attendre et vous devez avancer sur d autres parties des documents Comment faire sauter ce goulot d tranglement C est relativement simple 1 Par d faut vous travaillez sur la branche master Votre espace de travail contient des modifications que vous ne souhaitez pas committer avant validation carrereo gmail com Processus de r daction technique 18 Chapitre 3 R daction technique un processus industriel 2 Cr ez une nouvelle branche git checkout b ma branche 3 Committez vos modifications sur la no
63. ibute sets example title gt lt xsl call template name commonattributes gt lt xsl apply templates gt lt fo block gt lt xsl template gt par le code suivant lt xsl template match x contains tclass topic example gt lt fo block xsl use attribute sets example title gt lt xsl call template name insertVariable gt lt xsl with param name theVariableID select my example text gt lt xsl call template gt lt xsl apply templates select title gt lt fo block gt lt fo block gt lt xsl apply templates select x not contains class topic title Itext processing instruction gt lt fo block gt lt xsl template gt 2 D finissez dans les fichiers contenant les variables de langue tels que plugins org dita pdaf2 cfg common vars fr xml les variables de texte ins rer automati quement par exemple lt variable id my example text gt Exemple lt variable gt Pour obtenir un comportement homog ne vous devez d sactiver ce traitement pour les exemples des types de topics sp cifiques task notamment carrereo gmail com Processus de r daction technique 50 Chapitre 4 Format structur DITA XML 4 6 3 G n rer un PDF avec DITA Open Toolkit sous GNU Linux Ce didacticiel DITA XML est destin vous guider dans la mise en place et l utilisation de la cha ne de publication DITA OT dans un environnement GNU Linux Ubuntu ou Debian Pr requis
64. ic doit tre redondante l entreprise doit pr senter chacun de ses publics toute l information dont il a besoin sur le support qui lui est adapt Pour prendre l exemple le plus simple chaque support d information doit mentionner les coordonn es de la soci t Mais jusqu 50 de l information diss min e par l entreprise est r p t e En revanche la redondance de l information en interne engendre des co ts suppl mentaires allonge les cycles de produc tion et entra ne une baisse de l homog n it et donc de la qualit du contenu Il est donc primordial de diminuer et de mieux partager le contenu source et d en diminuer le volume Le r dacteur technique doit diviser l information en briques autonomes uniques standardis es et g n riques pour pouvoir l assembler la demande Il doit donc utiliser des modules structur s de mani re homog ne qui peuvent tre facilement manipul s par des applications pa sh Sources FIGURE 4 2 Les sources de la documentation doivent tre moins volumineuses que les livrables DITA XML est une architecture XML de r daction structur e destin e la cr ation de documents modulaires et la carrereo gmail com Processus de r daction technique 28 Chapitre 4 Format structur DITA XML r utilisation du contenu partir d une base commune de modules d information atomiques DITA XML le r dacteur technique peut fournir en temps r el
65. ient un vrai plat de spaghettis sans compter les risques de r f rence circulaire Les conref peuvent th oriquement tre combin s l infini mais les probl mes pratiques que cela engendre peuvent galement tre infinis conref Y conref conref FIGURE 4 18 Imbriquer les conref sur plusieurs niveaux puissant mais dangereux Pour r sumer la situation Il est tout fait possible d imbriquer plusieurs conref sources Le seul effet de bord n gatif porte sur la lisibilit du fichier contenant les conref L imbrication de conref sources et cibles est possible mais rapidement ing rable Il est impossible d imbriquer des conref cibles le contenu du conref du niveau sup rieur crasera les valeurs des conref du niveau inf rieur Maximiser l utilisation des conref pour faire baisser les co ts Recourir aux conref est le meilleur moyen dont dispose le r dacteur technique pour faire baisser spectaculairement les co ts et les d lais de publication de son contenu DITA XML surtout pour les documents multilingues De par la nature des informations qu elles contiennent les sections de type task ont un taux plus lev de r utilisation du contenu que celles de type concept ou reference conref conref co ES 3 source monolithique source modulaire FIGURE 4 19 Les conref modularisent de petits blocs d information Comme dans l exemple ci dessous il n est pas rare d o
66. imple Si vous donnez un fichier Git il le scinde directement en deux choses un contenu suite de bits ou blob un arbre lien entre le nom de fichier et le contenu Il le stocke ensuite dans l une des deux zones suivantes Pindex zone temporaire la base de donn es d objets zone persistante Lorsque vous ajoutez un fichier git add lt fichier gt Parbre est plac dans l index le contenu est plac dans la base d objets Lorsque vous commitez un fichier git commit l arbre est plac dans la base d objets Git ne compare jamais deux fichiers entre eux Il compare leur r sum qui est un nombre unique calcul partir de leur contenu Si le r sum de deux fichiers est identique le contenu de ces fichiers est indentique au bit pr s L historique de votre projet n est pas forc ment lin aire vous pouvez lui faire suivre plusieurs routes parall les les branches Vous ne pouvez cr er des branches qu partir d un commit Il faut voir les commits comme des ronds points la route tant l historique de votre projet partir desquels vous pouvez si vous le souhaitez prendre une autre direction dans votre projet Si vous cr ez une branche disons fest alors que des modifications de votre espace de travail ne sont pas commit es dans votre branche master les modifications que vous effectuerez s appliqueront aux fichiers non commit s de votre espace de travail S
67. important en d but de cycle de vie mais a rapidement un co t plus faible Comme une ampoule basse consommation un processus de r daction technique industriel diminue les co ts Il r duit galement le time to market co t initial l g rement sup rieur ou gal il am liore galement la qualit Co t moindre moins de volume cr er suppression des mises jour r p titives moins de volume traduire Time to market r duit r utilisation maximale du contenu risque z ro de perte de donn es Qualit am lior e briques d information facilement optimisables coh rence parfaite du contenu d entreprise Une documentation industrielle repose sur un format documentaire modulaire un format de r daction structur e une cha ne de production et de publication documentaire fiable Si la cha ne de cr ation et de publication choisie repose sur des logiciels open source le co t de mise en place et d appren tissage peut m me tre compens par l conomie sur les licences de logiciels En tout tat de cause de trop nombreuses soci t s de haute technologie ont industrialis leurs processus m tier mais laissent en friche la cr ation la gestion et la publication de leur contenu d entreprise Les co ts cach s r daction par des ing nieurs et non par un r dacteur technique comp tent mauvaise exploitation du capital immat riel diminution de la satisfaction client aug
68. inverse des machines Face cet tat de fait il convient de mettre un syst me de gestion de l information relative l volution de la documen tation qui soit tol rant l erreur humaine Il faut donc soit mettre en uvre des workflows sous un CMS utiliser le syst me de gestion de tickets utilis s pour la gestion des nouvelles fonctionnalit s du produit document par exemple Trac cr ation d un ticket par un d veloppeur mise en uvre du ticket par un r dacteur technique fermeture du ticket par le cr ateur du ticket publication de la documentation lorsque tous les tickets critiques sont ferm s Les fonctions principales d un CMS sont les suivantes gestion des m tadonn es workflows tra abilit Quel qu il soit le syst me de suivi doit offrir une visibilit et une tra abilit totales des modifications apport es la documentation technique quoi qui quand Ce syst me doit tre unique et exhaustif il doit centraliser toutes les demandes de modification de la documentation technique Si le document est disponible en plusieurs langues chaque ticket doit tre dupliqu pour chaque langue ou dans le cas d un CMS chaque langue doit correspondre un workflow distinct 3 7 Traduction Les contraintes de traduction doivent tre prises en compte en amont du processus r dactionnel Elles ont des implications autant sur le style r dactionnel que sur
69. itre de la section DITA XML correspondante et est donc propre chaque langue 2 D s le d but de votre projet DITA XML placez les fichiers de contenu DITA XML dans un sous r pertoire sp cifique la langue dans laquelle il est initialement r dig Par exemple product en_US images tasks topics et non product images tasks topics 3 Remplacez dans le fichier ditamap toutes les occurrences du nom du r pertoire propre la langue par une cha ne unique provisoire Par exemple utilisez la cha ne anguage code lt topicref href language code topics managing rights dita gt et non lt topicref href en_US topics managing rights dita gt 4 Pour g n rer les fichiers cibles vous pouvez maintenant a modifier dans le fichier demo fo build xml le param tre default locale b remplacer dans le fichier ditamap la variable de langue par le nom du r pertoire de langue c modifier le param tre de langue xml lang dans le fichier ditamap et dans les fichiers de contenu DITA XML d pour les fichiers cibles PDF modifier les dimensions de page A4 ou US letter par exemple selon la langue e g n rer les fichiers cibles f r tablir les valeurs initiales dans les fichiers sources Heureusement un script Bash GNU Linux simple permet d automatiser cela Pr requis Vous avez install DITA OT Votre projet DITA XML ne comporte qu un fichier ditamap
70. l che du temps de Git puis fusionn s Note Si vous avez effectu simultan ment les deux t ches sur un ou plusieurs fichiers pas de panique gr ce la commande git add p vous pouvez r partir vos modifications imbriqu es sur les commits idoines Lorsque vous lancez git status Vous vous apercevez alors que vos fichiers sont la fois pr ts et non pr ts tre commit s il y a deux tats des fichiers chaque tat repr sentant un stade partiel de votre travail et la somme des deux repr sentant la totalit des modifications que vous avez apport es Evidemment vous n avez plus acc s aux commits interm diaires mais c est ce que vous souhaitiez chaque commit unique repr sente un tat coh rent de votre contenu Ce workflow facilite galement le travail d quipe vous pouvez confier ces t ches deux membres diff rents de votre quipe chacun travaillant dans son espace local Les modifications du premier sont ensuite fusionn es avec celles du second dans son espace local via des patches Enfin les commits sont refactoris s avant de les placer sur le d p t central Important Moins vous r organiserez vos commits surtout chronologiquement plus le risque de devoir corriger ma nuellement des conflits sera faible Autrement dit git rebase ne doit pas tre une excuse pour ne pas planifier rationnelle ment son travail 3 5 2 Quel r f rentiel pour le travail de groupe Le r f rentiel le
71. late match x contains class topic example gt lt fo block gt lt xsl apply templates select text gt lt xsl apply templates select x not name title gt lt fo block gt lt xsl template gt Cependant tous les l ments texte non encapsul s dans des balises enfant de la balise lt example gt seront plac s en t te de l exemple avant les l ments encapsul s m me s ils sont plac s apr s dans le fichier source DITA XML Le fichier PDF affichera l exemple structur comme suit Voici mon exemple de chemin XPATH Texte non encapsul situ apr s un n ud enfant ancestor or self Il faut alors utiliser la syntaxe pipe condition bool enne ou pour modifier le chemin XPATH comme suit lt xsl apply templates select text x not name title gt Le r sultat final sera lt xsl template match x contains class topic example gt lt fo block gt lt xsl apply templates select text not name title gt lt fo block gt lt xsl template gt Le fichier PDF affichera l exemple structur comme suit Voici mon exemple de chemin XPATH ancestor or self Texte non encapsul situ apr s un n ud enfant 4 6 2 XSL FO ins rer automatiquement un titre pour les exemples Par d faut DITA OT n ins re pas automatiquement dans les fichiers PDF le texte Exemple devant le titre d un exemple contenu entre balises DITA XML lt exa
72. le nouveau terminal java jar lib dost jar i samples taskbook ditamap outdir transtype pdf2 Cette commande g n re un fichier PDF partir d un projet DITA XML d exemple F licitations vous avez compil votre premier projet DITA XML Vous trouverez le fichier cible taskbook pdaf dans le r pertoire Bureau fu11 DITA OT1 5 4 Vous pouvez maintenant compiler d autres projets en ignorant les tapes 1 et 2 40 http java com fr download manual jsp locale fr 41 http sourceforge net projects dita ot files DITA OTStableRelease DITAOpenToolkit1 5 4 DITA OT1 5 4_full_easy_install_bin zip download carrereo gmail com Processus de r daction technique 51 Chapitre 4 Format structur DITA XML 4 6 5 G rer les projets de documentation multilingues DITA XML DITA XML est un formidable format pour g rer les projets de documentation Pour les projets multilingues cependant le r dacteur technique doit cr er un fichier ditamap qui contient la structure de table des mati res des documents par version Ceci entra ne un risque d erreurs et d incoh rences Heureusement une m thodologie appropri e et un script d automatisation destin la cha ne de publication DITA OT rem dient ce probl me M thodologie de gestion des projets de documentation multilingues DITA XML 1 Le fichier ditamap ne doit pas comporter de section navtitle qui contient un titre en toutes lettres au lieu d extraire le t
73. ls xml_split xml_split 16 http www xmltwig org xmltwig carrereo gmail com Processus de r daction technique 35 Chapitre 4 Format structur DITA XML Documentation Documentation monolithique modulaire FIGURE 4 9 Une documentation modulaire offre une souplesse in gal e Le volume de contenu source est minimis ce qui diminue les co ts de cr ation mise jour et traduction du contenu d entreprise De plus le r dacteur technique peut g rer les processus de r daction validation et traduction module par module Les workflows peuvent ainsi tre parall lis s ce qui r duit les d lais de mise sur le march Les fichiers DITA XML peuvent en outre tre ais ment centralis s sous un r f rentiel unique tel qu un ECM syst me de gestion de contenu ou un VCS logiciel de gestion de versions Le capital immat riel de la soci t est ainsi pr serv 4 4 1 Un langage balises DITA XML est un langage balises le r dacteur technique structure l information dans des fichiers sources sans mise en page similaires aux fichiers sources de code informatique L utilisateur re oit un document cible par exemple un fichier PDF o les balises sont remplac es par une mise en forme typographique Si votre entreprise fournit ses clients une documentation technique au format MS Word le r dacteur technique et Putilisateur disposent des m mes supports d information il ny a pas de diff renciation entr
74. mentation des co ts de support etc peuvent tre consid rables Pourtant les solutions et les comp tences existent 2 1 De la r daction la communication technique Le but de la communication technique est de transformer les prospects en clients satisfaits Le r dacteur technique fournit au march l information dont il a besoin pour s lectionner valuer et utiliser une solution de haute technologie Au sein de l entreprise il est l interface entre les services R amp D et marketing l ext rieur il cr e le dialogue entre l entreprise et ses diff rents publics La communication technique est souvent r duite la r daction technique La r daction technique est destin e fournir la documentation des produits et intervient en aval de la vente La communication technique intervient d s l amont du processus de vente et accompagne le produit tout au long de son cycle de vie Destin e autant au grand public aux journalistes et aux prospects qu aux clients elle d passe et englobe la r daction technique destin e uniquement aux utilisateurs carrereo gmail com Processus de r daction technique 5 Chapitre 2 Documentation technique diminuer les co ts am liorer la satisfaction client Animation Site web Livre blanc Plaquette Magazine d entreprise Valeur marketing Guide de l utilisateur Niveau technique FIGURE 2 1 Supports de r daction marketing et technique La communi
75. ml dans le r pertoire racine de votre projet de documentation DITA XML puis collez la suite de commandes ci dessous en rempla ant lt r pertoire de langue gt par la valeur appro pri e en_US ou fr_FR par exemple R p tez cette tape pour tous vos r pertoires de langue export DIR schemas redaction technique org tar xzvf SDIR tar gz amp amp cd lt r pertoire de langue gt amp amp cp SDIR concepts schemas xml concepts amp amp cp SDIR faq schemas xml fag amp amp cp SDIR reference schemas xml reference cp SDIR tasks schemas xml tasks amp amp cp SDIR tasks schemas xml tasks amp amp cp S SDIR topics schemas xml topics amp amp rm rf DIR Vos r pertoires de langue doivent maintenant comporter les fichiers schemas xml appropri s fr_FR concepts schemas xml concepts schemas xml faq schemas xml reference schemas xml tasks 45 http www redaction technique org media rnc tar gz 46 http www redaction technique org media schemas redaction technique org tar gz carrereo gmail com Processus de r daction technique 56 Chapitre 4 Format structur DITA XML schemas xml topics schemas xml 6 Ouvrez un fichier de contenu DITA XML dita avec Emacs La syntaxe DITA XML appara t en couleurs Les endroits o le sch ma n est pas respect sont soulign s en rouge 7 Pour ins r
76. mple gt La syntaxe XSL FO offre cependant cette possibilit Supposons que le code source d un de vos fichiers DITA XML soit le suivant 38 http fr wikipedia org wiki XPath 39 http fr wikipedia org wiki XSL FO carrereo gmail com Processus de r daction technique 49 Chapitre 4 Format structur DITA XML lt example gt lt title gt XSL FO lt title gt Voici mon exemple de chemin XPATH lt codeblock gt ancestor or self lt codeblock gt lt example gt Vous souhaitez que le fichier PDF g n r affiche l exemple structur comme suit Exemple XSL FO Voici mon exemple de chemin XPATH ancestor or self et que si l exemple ne contient pas de titre il soit structur comme suit Exemple Voici mon exemple de chemin XPATH ancestor or self Par d faut cependant ce contenu sera structur comme suit dans le PDF par DITA OT XSL FO Voici mon exemple de chemin XPATH ancestor or self Il est toujours possible d entrer le texte entre les balises lt example gt mais XSL FO offre une mani re de proc der plus l gante et structur e Ins rer automatiquement une variable de texte avant le titre des exemples 1 Remplacez dans la feuille de style plugins org dita pdf2 xs1 fo commons xsl sous DITA OT 1 7 le template suivant lt xsl template match contains class topic example x contains class topic title gt lt fo block xsl use attr
77. ncept task Proc dure pas pas s quentielle et num rot e destin e r aliser une t che reference Informations de r f rence sur une liste d l ments tels que des options d un programme section 1 section 1 concept task reference section 2 section 2 concept task reference CEK EEK non structur structur FIGURE 4 3 Formats structur s et non structur s Sous un format non structur tel que le format traditionnel de FrameMaker rien ne contraint le r dacteur technique organiser l information selon son sens Si des r gles de r daction rigoureuses ne sont pas scrupuleusement suivies l information fournie l utilisateur risque d tre peu claire et difficile parcourir rapidement 1 http en wikipedia org wiki Adobe_FrameMaker carrereo gmail com Processus de r daction technique 29 Chapitre 4 Format structur DITA XML Avec des formats structur s tels que DITA XML en revanche le r dacteur technique se concentre sur le contenu l information est pr sent e l utilisateur selon une organisation coh rente et pr visible Pacc s l information est s quentiel et rapide l information peut facilement tre r organis e selon les besoins l utilisabilit du support d information fourni est optimale Les types d information de haut niveau tels que task sont divis s en types de plus bas niveau par exemple prereq Li
78. nement tr s proche de ce stade 4 http fr wikipedia org wiki RAW_ format_d 27image 5 Ce n est bien s r qu une analogie DITA XML tant un standard la diff rence du format RAW 6 http fr wikipedia org wiki Tagged_Image_File_ Format 7 http fr wikipedia org wiki Jpeg 8 Pour tre aussi exact que possible vous pouvez enregistrer une image JPEG au format TIFF mais cette image aura une qualit gale celle de l image JPEG inf rieure la qualit habituelle des images TIFF En revanche on ne peut ma connaissance pas enregistrer une image TIFF sous un format RAW 9 Le PDF est cependant plus riche en informations de mise en page appliqu es automatiquement partir d une feuille de style 10 LibreOffice propose une fonction d enregistrement au format DocBook mais tr s imparfaite le XML qu elle produit peut servir de base la cr ation d une version DocBook avec beaucoup d efforts Sauf maintenir deux versions du m me contenu le processus de migration de LibreOffice vers DocBook exige donc un arr t temporaire des livraisons des nouvelles versions de la documentation il doit donc tre soigneusement planifi carrereo gmail com Processus de r daction technique 31 Chapitre 4 Format structur DITA XML section section section ES concept SE concept ES t che ES task EE r f rence S reference FrameMaker migration DITA mise en place de la cha ne DITA FIGURE 4 6
79. neures C est un outil de plus destin r duire la redondance du contenu source Vous pouvez appliquer des cl s de filtrage en s rie condition ef en indiquant plusieurs valeurs s par es par des espaces dans les attributs product audience ou autre Exemple Pour indiquer qu une remarque est destin e la fois des lectriciens et des utilisateurs avanc s en voulant profiler information selon les publics suivants non lectriciens lectriciens d butants lectriciens experts Vous pouvez utiliser la structure suivante lt step audience electricians advanced gt lt cmd gt Ramenez 1 intensit sous la dose l tale de 150mA lt cmd gt lt step gt carrereo gmail com Processus de r daction technique 47 Chapitre 4 Format structur DITA XML Attention Une cl de filtrage mal positionn e peut entra ner une erreur de compilation En effet si le code non filtr est conforme au sch ma XSD DITA XML le code filtr peut ne pas l tre Exemple Le code suivant est correct avant filtrage lt thead gt lt row product a gt lt entry gt Commande lt entry gt lt entry gt Description lt entry gt lt row gt lt thead gt Apr s filtrage en revanche on obtient le code suivant lt thead gt lt thead gt Or selon le sch ma XSD les en t tes de tableaux doivent contenir au moins une ligne lt IENTITY thead content row gt Ce code est d
80. ns savoir qui ni dans quel but est un effort vain Avant d initier un projet de r daction technique il est indispensable de clairement le d finir Il convient notamment de d terminer son objectif Augmenter la notori t de l entreprise accro tre sa couverture m dias amener les prospects prendre contact avec la soci t r duire les co ts de support technique sa cible Grand public journalistes prospects clients sa forme Livre blanc mode d emploi ou guide de l utilisateur brochure et flyer site web magazine d entreprise print ou online carrereo gmail com Processus de r daction technique 9 Chapitre 3 R daction technique un processus industriel sa langue Suivant votre domaine d activit le projet sera d clin en une ou plusieurs langues principalement l an glais dans le secteur informatique son mode de diffusion Le document final peut tre publi sur un site Internet ou Extranet envoy sous forme de fichier joint par mail remis en mains propres au format papier etc L analyse des r sultats du projet donne ensuite de pr cieux renseignements pour am liorer encore l impact des projets suivants 3 2 Collecte de l information Le r dacteur technique collecte l information aupr s de diff rentes sources internes et externes l entreprise Une fois le projet de r daction technique clairement d fini le r dacteur technique collecte toute l information
81. nt B Document a y Grappes de fichiers modulaires FIGURE 3 6 Format source de r daction technique modulaire Certains traitements de texte proposent de g rer des documents modulaires mais ils le font mal Inversement un document DocBook ou DITA XML par exemple peut tre monolithique mais perd alors de sa souplesse Qu est ce qu un module d information Le syst me modulaire le plus connu au monde est certainement celui des briques Lego Adapt la documentation technique le principe des modules permet d am liorer la qualit des manuels techniques et la productivit du r dacteur technique Mais suffit il de convertir sa documentation de FrameMaker vers un format structur tel que DITA XML pour obtenir une documentation modulaire H las non Si le contenu de d part m lange les informations de tout type concepts proc dures pas pas r f rence il sera toujours possible de le convertir au format DITA XML en ne respectant pas rigoureusement la s mantique DITA XML Voire en modifiant les feuilles de style XSLT ou en sp cialisant les XSD pour les rendre plus laxistes Or si l on obtient au final un document se basant sur des fichiers correpondant chacun un sch ma XSD diff rent concept task ou reference on n obtient pas forc ment ainsi une v ritable documentation modulaire En effet essayez de construire alors un document ne regroupant que les fichiers d un seul type votre document a
82. ntenu DocBook vers DITA XML ce qui repr sente galement un effort quoique plus faible Mais votre contenu est imm diatement de meilleure qualit car plus structur Et vous pourrez rapidement cueillir tous les fruits de votre labeur notamment si une traduction de votre contenu dans une nouvelle langue est envisag e De mani re g n rale un professionnel a toujours int r t travailler sur le format le plus riche ne serait ce que pour tre pro actif et anticiper sur les nouveaux besoins 4 2 2 Migration de FrameMaker vers DITA XML Migrer de FrameMaker vers DITA XML ce n est pas comme enregistrer un document MS Word au format LibreOffice Aucun processus automatique ne permet de migrer un document non structur vers un format structur Dans le pire des cas selon la qualit de votre document de d part cela peut s apparenter transformer une friche en jardin la fran aise Mais une migration bien planifi e permet de passer au nouveau format sans perturber le rythme des livraisons Pour filer la m taphore si l on se fixe pour but de convertir un mar cage en parterre du ch teau de Versailles il convient de passer par l tape du jardin l anglaise soit un endroit certes non rigoureusement architectur mais tr s agr able vivre Bonne nouvelle si le r dacteur technique a utilis de mani re coh rente un jeu de styles limit et organis rationnellement son contenu FrameMaker il est d j certai
83. ntit qu une information de qualit est fournie l utilisateur Celui du jardin la fran aise permet en outre l entreprise de mieux ma triser son contenu et de r duire les co ts de production elle seule la pr sence d une des trois composantes processus quipe d di e et format adapt ne peut garantir un r sultat satisfaisant Confiez par exemple des outils permettant de g n rer du contenu au format DITA XML des colla borateurs dont la communication technique n est pas le m tier ou sans mettre en place de processus de gestion du cycle de vie de la documentation technique et vous obtiendrez des r sultats d cevants Seule la pr sence conjointe de ces trois l ments fournira un r sultat optimal 2 2 1 Un index est il utile dans un PDF A l heure des documents d mat rialis s un index est il un l ment indispensable d une bonne documentation technique La recherche en plein texte semble avoir d tr n l index Les notices techniques ne sont plus qu exceptionnellement fournies aux clients sous forme papier Ce dr le d objet qu est le PDF format d change entre un format source non destin aux clients et une version imprim e qui ne l est que de mani re marginale est entr dans les m urs La s quence de touches Ctrl F est un r flexe plus naturel aujourd hui pour qui recherche une information Un texte destin au Web recourra une grande dispersion terminologique pour accro
84. ocBook ne sont pas pleinement modulaires car les plus petits l ments d information manipulables ne sont pas g n riques ils contiennent des informations telles que la structure de table des mati res ou les r f rences crois es qui ne sont valables que dans un nombre limit de contextes 3 4 1 Documents monolithiques ou modulaires Le format source peut reposer sur des fichiers monolithiques ou sur des grappes de fichiers modulaires Les fichiers monolithiques par exemple MS Word LibreOffice ou FrameMaker centralisent tout le contenu dans un seul fichier facile manier mais qui limite le partage du contenu le risque de disposer d informations incoh rentes ou en doublon est alors important Document Document A B Fichiers monolithiques FIGURE 3 5 Format source de r daction technique monolithique Les grappes de fichiers modulaires par exemple DITA XML agr gent le contenu de multiples fichiers ce qui favorise le partage et la r utilisation de blocs de contenu Un tel syst me est difficile mettre en place au niveau de toute l entreprise mais devrait tre la norme pour une quipe de r daction technique 4 Ou tr s peu dans les fichiers de contenu il est seulement possible de mettre du texte en gras ou en italique pas d en changer la police le corps ou la couleur carrereo gmail com Processus de r daction technique 13 Chapitre 3 R daction technique un processus industriel Docume
85. ocument Format Application d une mise en page homog ne Possibilit de mise en page manuelle MS Word Non Oui FrameMaker Oui Oui DITA XML Oui Non Si contenu et mise en page sont intimement li s comme sous un traitement de texte il est difficile de modifier le contenu sans perturber la mise en page R sultat chaque publication d une nouvelle version d une documentation technique l quipe de r daction technique passe de longues heures corriger les erreurs de mise en page g n r es par le logiciel Le ph nom ne est moindre sous FrameMaker mais reste important Il est nul avec les formats DITA XML et DocBook les seules erreurs qui peuvent se produire sont des erreurs de compilation dues une syntaxe XML erron e ces erreurs sont facilement rectifiables Les fichiers sources d une documentation technique sont au format binaire ou texte Ce format est galement WYSIWYG ou structur Enfin ce format est modulaire ou monolithique Ce dernier aspect d termine la mani re dont le format g re le single sourcing selon une logique livre vers aide en ligne ou selon une logique aide en ligne vers livre Les formats disponibles peuvent donc tre class s selon le tableau suivant Format Texte Structur Modulaire FrameMaker natif Non Non Limit DocBook Oui Oui Limit DITA XML Oui Oui Oui FrameMaker et D
86. odologie rigoureuse et une cha ne de production fiable traduction el o o 3 ho o Ez D d finition collecte de cr ation du validation livraison du projet l information contenu 0 20 33 A al y E o H A format r f rentiel format source cible FIGURE 3 1 Processus de r daction technique Pour cr er et valoriser un contenu forte valeur ajout e pour l entreprise le r dacteur technique dialogue constamment non seulement avec tous les acteurs internes de la soci t mais aussi avec son cosyst me partenaires journalistes utilisateurs etc Il fournit ainsi aux diff rents publics l information dont ils ont besoin Ceci renforce l image de marque de la soci t am liore la satisfaction client et facilite la perception des avantages produit par les prospects Le r dacteur technique s appuie sur une cha ne de production aussi automatis e que possible En mettant en place un processus in dustriel et reproductible il diminue les co ts de production et fournit un niveau de qualit constant adapt aux buts de l entreprise 3 1 D finition du projet Un projet de r daction technique apporte une valeur ajout e aux produits et aide l entreprise mieux commercialiser son offre sur son march Mais comme pour les projets de R amp D ou de marketing la d finition du projet permet d en estimer le budget et les retomb es Communiquer des informations techniques sa
87. oir recours un logiciel de synchronisation de fichiers tels que rsync ou Unison ce dernier tant plus adapt la synchronisation bidirectionnelle en ligne de commande sous GNU Linux ou Windows ou un qui valent graphique tel Sync Toy Cependant ce type de logiciels se base sur la date de derni re modification des fichiers Lorsque l on met jour ou publie un livre FrameMaker notamment ceci peut cr er des conflits entre fi chiers FrameMaker enregistrant dans ces cas tous les fichiers du livre m me si leur contenu n a pas t modifi 3 5 4 Les syst mes de gestion de versions rustiques mais fiables Travailler sur des fichiers sources au format texte et non binaire est l occasion pour le r dacteur technique de g rer son contenu comme les d veloppeurs g rent leur code sous un syst me de gestion des sources tel que Git Subversion ou SourceSafe Ces syst mes favorisent le travail de groupe suppriment les copies de fichiers en doublons et r duisent le risque de perte de donn es presque z ro Sur des fichiers texte et non binaires un syst me de gestion de version offre des fonctionnalit s sup rieures pas de risque de pertes de donn es en cas de d faillance du r seau possibilit s de travail off line d connect pouss es non verrouillage des fichiers par les membres de l quipe qui les ont ouverts possibilit de restauration tr s fin
88. olutions qui permettent au r dacteur technique de les ma triser plus facilement Complexit Solution Syntaxe DITA XML IDE tel que XMetal ou nXML Gestion des relations entre des briques d information atomiques CMS d di tel que Componize ou DocZone Syntaxe de la feuille de style XSLT Logiciel graphique de cr ation de feuilles de style Pour une petite quipe de r daction technique l cueil principal sera la n cessit de mettre en uvre la charte graphique de l entreprise Les autres aspects peuvent tre g r s sans outil sp cialis avec une bonne communication et une s rie de bonnes pratiques 4 4 Du document la base documentaire modulaire Le mod le du livre est encore pr dominant pour cr er et g rer l information Mais le contenu d entreprise est souvent diss min dans de nombreux documents sous des formats h t rog nes Ceci se traduit par des doublons des incoh rences un co t de mise jour et de traduction lev et des retards de livraison Le r dacteur technique dispose cependant d autres mod les plus efficaces Le format de r daction structur e DITA XML propose de passer du mod le du livre celui du de la base documentaire modulaire Le contenu d entreprise repose sur des briques uniques qui peuvent tre assembl es dynamiquement la demande pour produire des documents sous diff rents formats cibles 15 http search cpan org dist XML Twig too
89. on et la mise en page s op rent sur les m mes fichiers par exemple des fichiers FrameMaker des fichiers diff rents par exemple des fichiers de contenu XML et une feuille de style XSLT Dans un fichier FrameMaker la s paration du fond et de la forme est lev e mais pas totale le contenu et la mise en page sont plac s dans le m me fichier FrameMaker applique une maquette de page homog ne tout un fichier mais autorise l ajout manuel d l ments de mise en page La m me maquette peut tre dupliqu e pour tout le document ou une maquette diff rente peut tre utilis e pour chaque fichier qui compose ce dernier texte docbook monolithique modulaire framemaker binaire FIGURE 3 4 Formats sources degr de modularit et format Les formats sources peuvent tre class s selon leur degr de modularit et leur format de fichier 2 http fr wikipedia org wiki RAW_ format_d 27image 3 Si le r dacteur technique met lui m me en page ses documents il change de r le lorsqu il effectue cette op ration carrereo gmail com Processus de r daction technique 12 Chapitre 3 R daction technique un processus industriel Les formats XML structur s DocBook et DITA XML appliquent une maquette de page homog ne tout un document et n autorisent pas l ajout manuel d l ments de mise en page ni l application de maquettes diff rentes aux diff rents fichiers qui composent le d
90. onc incorrect et entra ne l chec de la compilation 4 6 Didacticiels DITA XML et XSL FO Les didacticiels suivants aideront le r dacteur technique mettre en place et utiliser une cha ne de cr ation et de publi cation DITA XML libre DITA XML est un langage de r daction structur e qui permet de cr er des documents sans se soucier de leur aspect final sur diff rents supports XSL FO est un langage qui permet de r organiser et filtrer le contenu XML et de lui appliquer une mise en page l aide d une feuille de style Un ensemble de fichiers DITA XML contient tout le contenu relatif par exemple un produit Diff rentes feuilles de style XSL FO permettront de publier ce contenu en PDF en HTML ou sous un autre format en appliquant des transformations complexes Le r sum de chaque section du document final pourra par exemple appara tre dans la version HTML et non dans la version PDF De m me si un produit doit tre fourni en marque blanche diff rents clients une mise en page totalement diff rente peu tre appliqu e sa documentation en sp cifiant simplement un autre jeu de feuilles de style lors de la g n ration du livrable Op ration qui n est pas envisageable en pratique avec des solutions traditionnelles de type FrameMaker 4 6 1 XSL FO filtrer du contenu selon des conditions sauf et ou Imaginons que vous vouliez filtrer les n uds enfants de la balise DITA XML lt example gt et af
91. ons exporter des variables pour rendre le script plus concis et plus lisible export w lt x gt export m w Sw Sw w w w w Sw echo Belle marquise vos beaux AM yeux me font mourir d amour sed s m d lt x gt u 9 18 M6 M7 NIM M2 3 M4 ASH D amour mourir me font belle marquise vos beaux yeux Nous pouvons maintenant facilement redistribuer les r f rences arri res pour obtenir toutes les variations du ma tre de philosophie echo Belle marquise vos beaux AM yeux me font mourir d amour sed s m d lt x gt u 3 M5 M4 M9 M6 M7 NIM M2 8 Vos yeux beaux d amour me font belle marquise mourir echo Belle marquise vos beaux AM yeux me font mourir d amour sed s m d lt x gt u 8 3 M4 M5 MIM M2 M9 6 7 Mourir vos beaux yeux belle marquise d amour me font echo Belle marquise vos beaux yeux me font mourir d amour sed s m d lt x gt u 6 7 3 5 4 8 MML 2 ASH Me font vos yeux beaux mourir belle marquise d amour Moli re et GNU Linux R crivons le dialogue de M Jourdain et de son ma tre de philosophie en style geek MONSIEUR JOURDAIN Je voudrais donc lui afficher sur la sortie standard Belle marquise vos beaux yeux me font mourir d amour Mais je voudrais que cela f t mis d une mani re galante que cela f t tourn gentiment MA TRE DE PHILOSOPHIE On les peut mettre premi rement comme vou
92. ort de r daction technique est celui sous lequel l audience du message y acc dera Il est diff rent de celui sous lequel le r dacteur technique cr e le contenu Le single sourcing permet de g n rer plusieurs livrables des formats diff rents partir d un m me format source A partir des fichiers sources valid s les livrables sont g n r s selon l une des m thodes suivantes Totalement automatique Par exemple livre blanc du format structur DITA XML au format cible PDF via DITA OT DITA Open Toolkit Semi automatique Par exemple contenu au format DITA XML export en HTML puis coll sous un CMS Manuelle Par exemple plaquette marketing au format traitement de texte ou DITA XML mise en page sous Indesign export e en PDF puis imprim e selon la fr quence de publication du document final des filtres d import XML peuvent galement tre mis en place Plus le processus est automatis plus le risque d erreur est faible et plus la publication et la mise jour sont ais es L automatisation facilite galement le single sourcing qui consiste g n rer plusieurs livrables des formats cibles diff rents partir d un m me format source Un projet au format DITA XML peut ainsi tre livr sous forme de fichier PDF d aide compil e Windows d aide JavaHelp de site en HTML etc Le XML offre en ce domaine des possibilit s quasi illimit es 3 9 Livraison Le r dacteur technique livre le doc
93. par lots de t ches sur un contenu et non par fichier Ce fonctionnement peut sembler peu intuitif si l on a l habitude de travailler fichier par fichier et non t che par t che Mais une fois que l on a adapt ses habitudes de travail ce workflow on s aper oit que l on dispose d un historique beaucoup plus facilement exploitable qu il est beaucoup plus facile de g rer des versions concurrentes d un m me contenu dans des branches de d ve loppement parall les Imaginons que vous ayez identifi deux types de modifications majeurs apporter votre contenu les synopsis d un programme en ligne de commande les corrections grammaticales du texte Si votre contenu est r parti dans un ensemble de fichiers modulaires vous pourriez d cider d apporter en m me temps les deux types de modifications dans chaque fichier un un Pour r partir le travail sur un groupe de r dacteurs techniques il vous suffit d allouer chacun un lot de fichiers Ce workflow n est pas le plus adapt Git Si vous utilisez ce syst me de gestion de versions il est pr f rable de diviser le travail en deux lots de t ches que l on appelera synopsis et texte appliqu s concurremment sur tous les fichiers Les contraintes de production vous obligeront souvent scinder ces deux lots de t ches en sous lots que vous serez oblig de faire alterner Vous committez chaque sous lot chaque fois qu il est
94. peut l instar d un constructeur automobile proposant sans cesse de nouveaux mod les par assemblage d l ments standardis s proposer par exemple les documents suivants Guide de Putilisateur Th mes syst matiquement organis s en concept et proc dures pas pas Document de pr sentation Concepts Quikstart Proc dures pas pas Manuel de r f rence Informations de r f rence Pour ce faire le r dacteur technique prendra soin de placer les l ments li s un contexte particulier dans les structures ditamap et non dans les fichiers de contenu DITA XML En particulier les r f rences crois es doivent tre indiqu es dans une reltable plac e dans la ditamap si le document doit renvoyer au document B dans la ditamap 1 il doit pouvoir tre galement utilis sans modification dans la ditamap 2 o le document B n est pas inclus L organisation des r pertoires de travail doit galement permettre l utilisation de liens relatifs notamment vers les images qui ne seront jamais cass s 4 4 4 Le single sourcing un format source plusieurs formats cibles Le single sourcing est un sujet qui a longtemps divis les r dacteurs techniques des supports de r daction technique diff rents tels qu une aide en ligne et un manuel imprim doivent ils proposer un contenu radicalement diff rent ou peuvent ils tre g n r s partir du m me contenu source Les contraintes de productivit et la r duction d
95. plus fr quemment utilis pour stocker des fichiers informatiques est le dossier ou r pertoire Si ce d p t est parfaitement adapt la gestion de fichiers par un utilisateur unique sur son disque dur local il montre rapidement ses limites pour le travail de groupe Pour travailler sur un fichier le r dacteur technique utilise un programme qui lit le fichier sur son disque dur et en charge une copie en m moire vive Les modifications s effectuent sur cette copie Lorsque le r dacteur technique enregistre ses modifications le programme crase sur le disque dur la version pr c dente du fichier La version pr c dente est donc d finitivement supprim e sauf si le programme a cr une copie de sauvegarde ou si le r dacteur technique a utilis la fonction Enregistrer sous et non Enregistrer pour cr er une nouvelle version du fichier Dans le premier cas il n existe que deux versions du fichier un instant donn la version n et la version n 1 Dans le second cas le r dacteur technique peut cr er autant de versions qu il le souhaite par exemple en ajoutant le suffixe 1 2 etc au nom du fichier Les programmes ne g rent cependant pas la modification concurrente d un m me fichier par plusieurs r dacteurs tech niques Dans le cas d un fichier disponible sur un disque r seau imaginons qu Ars ne et Louise ouvrent la m me version de ce fichier sous un diteur de texte Chacun apporte des modifications diff rente
96. pugs IA A Ge estion des ii javamelP versions sources a gocument modulaire Ja G FIGURE 1 1 Sources de documentation modulaires au format texte Elle doit r pondre id alement aux crit res suivants pas de vendor lock in ind pendance du format et de l diteur de contenu cha nes de publication libres et gratuites mise en page totalement automatis e Il y a quelques ann es encore les seuls outils permettant de fournir des livrables de qualit au format PDF ou HTML reposaient sur des formats binaires et propri taires qui s int graient mal aux syst mes de gestion de versions des quipes de d veloppement R sultat r alis e part la documentation technique r pondait difficilement aux m mes exigences de qualit et de d lai de mise sur le march que les produits carrereo gmail com Processus de r daction technique 1 Chapitre 1 Lib rez vos informations de leurs silos DocBook puis DITA Darwin Information Typing Architecture XML et reStructuredText ont chang la donne ces for mats texte peuvent tre modifi s avec tout type de programme du simple diteur de texte l IDE Integrated Development Environment graphique et s int grent parfaitement sous Subversion Git ou tout autre syst me de gestion de versions 1 2 Les sources de ce document sont g r es sous Git Ce document a t initialement d velopp sous WordPress L impossibilit d e
97. r echo Cher docteur ces grands malheurs vous font pleurer d amertume gt variations txt echo Petit gar on cette bonne glace te fait saliver d envie gt gt variations txt echo Vaste oc an la forte houle te fait tanguer d ivresse gt gt variations txt Pla ons les diff rentes commandes sed dans un script diff rent chacune echo s p u 9 8 6 7 AIAL 2 3 4 5 echo s p u 3 5 4 9 6 7 NINI 2 184 echo s p u 8 3 4 5 1 1 2 9 6 7 echo s Sp u 6 7 3 5 4 8 1 1 2 9 gt molierel sed gt moliere2 sed gt moliere3 sed gt moliere4 sed Ex cutons maintenant en boucle tous les scripts sed sur toutes les lignes du fichier for i l i lt 5 i do while read s do echo s sed f moliere i sed done lt variations txt done D amertume pleurer vous font cher docteur ces grands malheurs D envie saliver te fait petit gar on cette bonne glace D ivresse tanguer te fait vaste oc an la forte houle Ces malheurs grands d amertume vous font cher docteur pleurer Cette glace bonne d envie te fait petit gar on saliver La houle forte d ivresse te fait vaste oc an tanguer Pleurer ces grands malheurs cher docteur d amertume vous font Saliver cette bonne glace petit gar on d envie te fait Tanguer la forte houle vaste oc an d ivresse te fait Vous font ces malheurs grands pleurer cher docteur d amertume
98. r hension de son sujet La r daction du contenu et son appr hension par son destinataire deviennent alors ais es C est un aspect fondamental du m tier de r dacteur technique Le r dacteur technique apporte ainsi une v ritable valeur ajout e au produit qu il documente 1 M me si les formats qui distinguent le contenu de la mise en page sont dans leur principe plus aptes la mise en uvre de la philosophie KISS 2 Ce genre de phrase est d ailleurs souvent impossible traduire carrereo gmail com Processus de r daction technique 7 Chapitre 2 Documentation technique diminuer les co ts am liorer la satisfaction client 2 4 Formats et outils Lorsqu une entreprise d cide d industrialiser la r daction technique elle se pose d embl e la question des outils Or plut t que les outils ce sont les formats sous jacents qui sont le point essentiel La plupart des diteurs afin de disposer d un march captif oblig de r guli rement payer des mises jour de leurs produits ont en effet d velopp des formats propri taires que seuls leurs logiciels sont m me de modifier Un fichier MS Word ou un fichier FrameMaker ne peuvent ainsi tre modifi s que via les outils ponymes Choisir un tel format risque donc de limiter les choix ult rieurs de l entreprise et de se r v ler co teux il faut une licence par utilisateur qu il soit r dacteur technique contributeur occasionnel ou traducteur
99. rd hui effectuer 2 http fr wikipedia org wiki XML_Schema 3 https github com olivier carrere redaction technique org tree DocBook carrereo gmail com Processus de r daction technique 30 Chapitre 4 Format structur DITA XML Si votre contenu tait une photo nous pourrions faire l analogie suivante Format de Format de photo contenu DITA XML RAW DocBook TIFF 6 PDF JPEG Le passage de RAW en TIFF et de TIFF en JPEG est destructif et ne peut se faire en sens inverse Y Y pdf Oe FIGURE 4 5 Un processus non r versible Le PDF est s mantiquement plus pauvre que DocBook lui m me plus pauvre que DITA XML Si votre entreprise tient absolument utiliser du DocBook il est toujours loisible de g n rer le contenu DocBook partir d un contenu source au format DITA XML condition que le contenu source reste au format DITA XML c est dire condition qu aucune modification apport e au contenu DocBook ne soit sauvegard e et que le format DocBook ne soit qu une tape de la g n ration des livrables au m me titre que le format FO vous b n ficiez ainsi des fonctionnalit s avanc es de r utilisation du contenu que propose DITA XML L effort de migration d un format non structur est certes un peu plus important vers DITA XML que vers DocBook puisque vous devez injecter plus d informations s mantiques Vous devez galement migrer le co
100. rmations glan es aupr s des diff rents acteurs de la soci t Jouant le r le de Candide il est le premier repr sentant des utilisateurs et se doit de tester les produits dans des conditions proches des leurs Un conte chinois narre comment des aveugles se sont retrouv s confront s un l phant Aucun d entre eux et pour cause n ayant une perception globale de l animal chacun en eut une image diff rente celui qui en tenait une patte le 1 http trac edgewall org carrereo gmail com Processus de r daction technique 10 Chapitre 3 R daction technique un processus industriel prenait pour un arbre celui qui en treignait la trompe le confondait avec un serpent celui qui avait empoign une d fense l identifiait une lance et celui qui s agrippait une de ses oreilles croyait qu il s agissait d un ventail FIGURE 3 3 Conte des aveugles et de l l phant Le r dacteur technique qui demande aux diff rents intervenants de l entreprise quoi sert le produit dont il doit cr er la documentation et comment il fonctionne se retrouve comme celui qui demande aux aveugles quoi ressemble un l phant pour la R amp D il s agit de code l gamment r dig pour le marketing d une offre positionner face la concurrence sur son march pour le support technique d un ex cutable dont il faut corriger les bugs etc Pour avoir une vision r aliste de l objet qu il est c
101. rocessus de r daction technique 36 Chapitre 4 Format structur DITA XML correspond au type d information qu il veut pr senter De base DITA XML propose les types d information suivants concept Texte g n raliste du type introduction ou pr sentation task Proc dure pas pas destin e r aliser une t che reference Information de r f rence du type explication de param tres de commandes Chacune de ces cat gories de haut niveau propose un jeu de balises de plus bas niveau qui lui est propre Si le r dacteur technique r dige un document technique il y a toutes les chances pour que l information qu il a collect e et qu il doit organiser fasse partie de l une de ces trois cat gories Cette division en types d information oblige donc d entr e de jeu le r dacteur technique structurer l information L utilisateur y gagne en facilit et rapidit d acc s l information et en utilisabilit globale de la documentation technique 4 4 3 Organisation la demande du contenu Les briques d information peuvent tre assembl es la demande dans des structures de table des mati res externes les ditamap L organisation de l information sous DITA XML n est pas fig e Les briques peuvent tre organis es dans diff rentes structures hi rarchiques selon l volution des besoins Si le r dacteur technique a pris soin de construire des briques d information atomiques et g n riques il
102. s avez dit echo Belle marquise vos beaux yeux me font mourir d amour Ou bien export declaration Belle marquise vos beaux yeux me font mourir d amour echo declaration Ou bien carrereo gmail com Processus de r daction technique 16 Chapitre 3 R daction technique un processus industriel export w lt x gt export m Sw Sw w w w Sw w Sw echo Sdeclaration sed s m d lt x gt u 9 8 M6 M7 MAM M2 M3 M4 5 Ou bien echo S declaration sed s m d lt x gt u 3 5 M4 M9 M6 M7 MIM M2 8 Ou bien echo declaration sed s m d lt x gt u 8 13 M4 M5 AMIM M2 M9 6 7 Ou bien echo declaration sed s m d lt x gt u 6 7 3 M5 4 M8 AMIM M2 9 Beaucoup d efforts Certes beaucoup d efforts pour pas grand chose me direz vous Mais imaginons un fichier qui contiennent 1000 phrases de la m me structure Cher docteur ces grands malheurs vous font pleurer d amertume Petit gar on cette bonne glace te fait saliver d envie Vaste oc an la forte houle te fait tanguer d ivresse Ceci est en l occurrence peu probable mais il est en revanche monnaie courante de trouver dans la documentation tech nique des phrases de m me structure pour des raisons d homog n it stylistique Pour effectuer nos tests sur un chantillon pla ons les trois phrases pr c dentes dans un fichie
103. s dans sa copie charg e en m moire vive puis enregistre son travail Ars ne enregistre tout d abord ses modifications puis Louise la prochaine ouverture du fichier seules les modifications de Louise figureront dans le fichier Pour viter ce genre de situation de nombreux programmes verrouillent les fichiers ouverts Ils ne sont donc disponibles qu en lecture tant que l utilisateur qui les modifie en a une copie en m moire vive c est dire tant qu il ne l a pas ferm Il n est donc pas possible avec ce syst me de travailler plusieurs sur le m me fichier et d effectuer par exemple des modifications transverses par lot comme modifier le chemin de toutes les images carrereo gmail com Processus de r daction technique 20 Chapitre 3 R daction technique un processus industriel Si le programme utilis ne verrouille pas les fichiers ouverts une coordination de tous les instants doit s instaurer entre les membres de l quipe 3 5 3 Les r pertoires r seau partag s peu adapt s au travail de groupe Les fichiers partag s par une quipe de r daction technique sont souvent stock s dans un r pertoire partag sur le r seau Les r dacteurs techniques travaillent directement sur les fichiers partag s ce qui pose les probl mes suivants risque de pertes de donn es en cas de d faillance du r seau possibilit s de travail off line d connect limit es verrouillage de
104. s fichiers par les membres de l quipe qui les ont ouverts M me fr quemment sauvegard s les r pertoires ne sont pas un r f rentiel s r pour les donn es la granulom trie de la sauvegarde est le r pertoire sa fr quence n est souvent que quotidienne En cas de perte de donn es la restauration se fait r pertoire par r pertoire et non fichier par fichier et porte sur des versions dont l anciennet d pend de l administra teur syst me et non du r dacteur technique Fouiller dans les archives est une op ration fastidieuse qui peut elle m me tre source d erreurs en l absence d une comparaison fiable et ais e entre plusieurs versions des fichiers le r dacteur technique peut facilement supprimer des modifications qu il aurait souhait conserver en voulant en restaurer d autres Copier un fichier du r seau pour le modifier sur son disque dur personnel puis craser la version du r seau par la version locale est une op ration des plus p rilleuses les membres de l quipe ne sont pas inform s du fait qu un autre membre modifie ou non le m me fichier en m me temps qu eux l un des r dacteurs techniques devra alors renoncer toutes ses modifications lors d une copie manuelle des fichiers que ce soit via un gestionnaire de fichiers graphique ou en ligne de com mande le r dacteur technique peut facilement craser la version la plus r cente par la plus ancienne on pr f rera alors av
105. ste de points obligatoires pr alables la r alisation d une t che steps S rie d tapes de la proc dure stepxmp Exemple de r alisation d une tape Les r gles syntaxiques interdisent au r dacteur technique de faire figurer une proc dure pas pas dans une section d un autre type que task Le r dacteur technique dispose donc d un v ritable mod le de r daction qui l aide pr senter des informations Minimalistes Selon le principe de design less is more l utilisateur ne dispose que de l information dont il a be soin une section task par exemple ne contient que des pr requis une proc dure et quelques autres l ments sp cifiques toutes les informations conceptuelles ou de r f rence sont plac es dans des sections part Compl tes L utilisateur dispose de toute l information dont il a besoin une section de type task sans proc dure n est pas une section DITA XML valide et ne pourra pas tre publi e il est m me possible de mettre en uvre un m canisme v rifiant automatiquement avant publication la pr sence de blocs d information facultatifs selon le sch ma XSD DITA XML mais que le r dacteur technique juge obligatoires tels que le r sultat d une proc dure Coh rentes Les informations de m me type sont pr sent es dans le m me ordre et avec la m me mise en page les blocs d information identiques r p t s diff rents endroits tels qu une remarque sont issus d une se
106. tes d une fiabilit optimale J aurais quelques scrupules et quelques inqui tudes sur le fait de leur confier enti rement la gestion et l archivage des fichiers sources de la documentation Une s lection rigoureuse de la solution s impose associ e une proc dure de sauvegarde et de restauration prouv e 14 http www git scm com 15 chaque d p t du fichier sur le CMS et non chaque enregistrement de son travail par le r dacteur technique carrereo gmail com Processus de r daction technique 23 Chapitre 3 R daction technique un processus industriel 3 5 6 Base de donn es SQL Dans le cas d un CMS de type Drupal Joomla ou WordPress le r f rentiel est une base de donn es SQL Il conserve un historique mais uniquement article par article et ne permet pas la recherche et le remplacement de texte travers tout le contenu Cela peut justifier le choix de g rer le contenu sous jacent du CMS sous forme de fichiers texte 3 5 7 Un r f rentiel unique Id alement tout le contenu peut tre plac sous un r f rentiel unique par exemple le logiciel de gestion de versions Git Ceci en maximise la r utilisation la coh rence et la qualit Si le contenu est au format DITA XML ou DocBook par exemple on peut exploiter au mieux les capacit s de single sourcing de ces formats pour le publier sous la forme appropri e Le contenu devient un r seau de modules d information il faut alors g
107. title gt lt chapter href texte conditionnel dita gt lt bookmap gt Collez le code suivant dans un fichier et enregistrez ce dernier sous le nom de electriciens ditaval dans le r pertoire DITA 0T1 5 4 lt xml version 1 0 encoding UTF 8 gt lt val gt lt prop att audience val electriciens action include gt lt prop att audience val plombiers action exclude gt lt val gt Collez le code suivant dans un fichier et enregistrez ce dernier sous le nom de plombiers ditaval dans le r pertoire DITA 0T1 5 4 lt xml version 1 0 encoding UTF 8 gt lt val gt lt prop att audience val electriciens action exclude gt lt prop att audience val plombiers action include gt lt val gt Ouvrez un terminal et entrez la commande suivante dans le r pertoire DITA 0T1 5 4 java jar lib dost jar i texte conditionnel ditamap filter electriciens ditaval outdir transtype pdf2 Ouvrez le fichier texte conditionnel pdf il contient des informations destin es aux plombiers et aux lectriciens uniquement aux lectriciens Ouvrez un terminal et entrez la commande suivante dans le r pertoire DITA OT1 5 4 java jar lib dost jar i texte conditionnel ditamap filter plombiers ditaval outdir transtype pdf2 Ouvrez le fichier texte conditionnel pdf il contient des informations destin es aux plombiers et aux lectriciens uniquement aux plombiers
108. tre sa visibilit sur les moteurs de recherche L emploi des synonymes est de rigueur pour donner au lecteur potentiel plusieurs chemins d acc s la source d information qui peut l int resser Les moteurs de recherche ont rendu l index caduc Si la documentation technique utilise une terminologie coh rente l efficacit de la recherche en plein texte est r duite si le r dacteur technique a utilis uniquement le terme r pertoire le lecteur qui recherche le mot dossier passera c t de l information qu il recherche L index s il est bien r alis a alors toute son utilit Seul probl me cr er un bon index demande un effort important en toute fin de projet juste avant l heure de la livraison Et fournir un mauvais index n a aucun int r t ni pour le client ni pour l entreprise Un index est donc paradoxalement plus utile pour une bonne documentation que pour une mauvaise du moins une docu mentation dont la terminologie n est pas coh rente Mais son rapport co t utilit est faible C est un luxe que l entreprise peut rarement s offrir mais certainement pas le premier aspect qualitatif qu il faut am liorer Un index est la cerise sur le g teau d une documentation technique le plus important reste le g teau 2 3 Principe de simplicit KISS Le principe KISS Keep it simple stupid n est pas sp cifique la r daction technique Il s agit d un principe g n ral d ing nierie qui
109. ule et m me source et sont donc strictement identiques 4 2 1 DocBook ou DITA XML Certaines entreprises ont parfois un contenu existant au format DocBook G r souvent par les acteurs les plus techniques de la soci t il coexiste la plupart du temps avec d autres contenus au format FrameMaker ou traitement de texte S il est d cid de f d rer tout le contenu d entreprise sous un seul format il semble naturel de capitaliser les efforts fournis sur la cha ne de cr ation et de publication DocBook et de s lectionner ce format C est pourtant se priver des gains de productivit spectaculaires offerts par DITA XML Il est facile de g n rer du DocBook partir de DITA XML DITA OT propose par d faut ce format cible au m me titre que le PDF ou le HTML L op ration inverse ne peut pas tre totalement automatis e Pourquoi Y r y aw tiff jpeg De Qe FIGURE 4 4 Un processus non r versible r Il n est pas possible de migrer automatiquement des donn es de formats pauvres vers des format riches en information Tout simplement parce que le contenu au format DITA XML contient plus d informations Passer d un format plus riche un format plus pauvre en information est une op ration entropique qui peut facilement tre automatis e Par exemple g n rer un PDF partir de DITA XML Effectuer l op ration inverse exige d injecter de l intelligence op ration que seul T tre humain peut aujou
110. ument son destinataire de la mani re appropri e animation publi e sur un site de streaming plaquette distribu e dans les salons ou laiss e en client le par les ing nieurs commerciaux journaux envoy s aux clients site Internet mis jour document mis en ligne en PDF ou distribu sous forme de guide imprim 19 Dans le cas d une photo le format cible est le format JPEG http fr wikipedia org wiki Jpeg qui est utilis pour l affichage Web ou l impression et sur lequel les modifications ne peuvent tre annul es une fois ferm le logiciel de retouches 20 Ceci est automatisable par un script le CMS Drupal propose galement un module DITA integration for Drupal http drupal org project dita carrereo gmail com Processus de r daction technique 27 Chapitre 4 Format structur DITA XML 4 Format structur DITA XML Diminuer les co ts de production et de traduction r duire les d lais de mise sur le march ou time to market et am liorer la qualit de la documentation Voil les d fis que doit relever aujourd hui le r dacteur technique L un des meilleurs moyens d y parvenir consiste r duire le volume source de la documentation et mieux g rer le contenu d entreprise docbook reStructuredText framemaker FIGURE 4 1 Formats de documentation technique degr s de structuration L information que le r dacteur technique fournit au publ
111. ur partager les informations propres chaque type Je r serve le type composite un fichier central fourre tout contenant des informations partag es entre diff rents types de topics Tous les conref sources d un fichier donn doivent avoir un ID unique dans ce fichier veillez utiliser des noms explicites pour les humains vos fichiers dita contenant des conref cibles deviendront sinon rapidement illisibles Utiliser le n ud XML de plus bas niveau Le r dacteur technique doit utiliser comme source du conref le n ud DITA XML de plus bas niveau contenant l infor mation partager Le but des conref tant de g rer des blocs d information de faibles dimensions il est logique de les manipuler au niveau de la plus petite structure XML encapsulant l information m me si cette structure pour tre compatible avec le sch ma XSD de la section DITA XML o elle intervient doit elle m me tre incluse dans des structures XML plus grandes conref Y n ud n ud XML FIGURE 4 15 Placement du conref sur le n ud XML de plus bas niveau Vous voulez par exemple r utiliser la phrase Cliquez sur OK Vous ne pouvez cependant pas indiquer dans le fichier contenant les conref sources uniquement le code suivant lt cmd gt Cliquez sur OK lt cmd gt Pour tre conforme au sch ma XSD votre code doit au moins tre structur comme suit 32 http docs oasis open org dita v1 1 0S archspec conref html
112. ura toutes les chances d tre incomplet et incoh rent Cette documentation n est pas modulaire car elle ne repose pas sur de v ritables modules d information Un module est un l ment atomique complet et coh rent qui peut tre r utilis dans diff rents contextes Si vous avez divis votre document monolithique original en une multitude de fichiers vous n avez pas encore cr de modules d information La seconde tape consiste r crire chaque fichier selon par exemple l approche minimaliste pour le rendre plus g n rique et en faire un v ritable module Il faut videmment adopter une approche structuraliste et d cider du contenu de chaque module dans la perspective de l architecture documentaire globale De m me des mentions telles que Voir la section suivante devront tre remplac es par des ref rences crois es Id alement ces r f rences crois es ne se situent pas dans les fichiers de contenu proprement dit sous la forme lt related links gt lt link href content dita content gt lt related links gt mais dans une section reltable propre chaque fichier ditamap Les modules sont ainsi parfaitement d contextualis s et les informations de structure telles que les r f rences crois es sont plac s dans des fichiers ne comportant pas de contenu textuel 3 4 2 Fichiers binaires ou texte Les formats sources sont des formats binaires ou texte Les formats binaires si on les ouvre
113. utiliser ou recycler bon escient le contenu existant 2 2 Les trois niveaux de la documentation technique Si l on compare la documentation technique un jardin on peut la classifier selon les niveaux suivants Friche Pas d utilisation de processus documentaire Cr ation de la documentation par des quipes non d di es Utilisation de formats non adapt s ou utilisation incoh rente de formats adapt s Jardin l anglaise Utilisation de processus documentaires fiables Cr ation de la documentation par des quipes d di es Utilisation coh rente de formats adapt s mais non structur s Jardin la fran aise Utilisation de processus documentaires fiables Cr ation de la documentation par des quipes d di es Utilisation coh rente de formats structur s Les formats non adapt s la r daction technique sont par exemple les formats de traitement de texte qui ne dissocient pas suffisamment la mise en page du contenu Les formats adapt s sont les formats de type FrameMaker qui dissocient relativement la mise en page du contenu mais ne sont pas s mantiques Les formats structur s sont les formats s mantiques de type DocBook ou DITA XML carrereo gmail com Processus de r daction technique 6 Chapitre 2 Documentation technique diminuer les co ts am liorer la satisfaction client Le stade du jardin l anglaise est d j tr s satisfaisant et gara
114. uvelle branche git add mes fichiers git commit m mon message de commit 4 Vous repassez sur la branche master git checkout master et passez votre deuxi me t che 5a Si votre premi re t che n est pas valid e vous repassez sur la branche provisoire git checkout ma branche et faites un nouveau commit que vous pourrez fusionner avec le ou les pr c dents apr s validation 5 Lorsque vous recevez la validation de la premi re t che vous mettez votre travail en cours de c t git stash 6 Vous fusionnez la branche provisoire avec la branche master git merge ma branche 7 Vous r cup rez votre travail en cours git stash pop Si vous n avez pas besoin d effectuer deux lots de t ches en parall le vous pouvez sans probl me travailler dans votre espace local Si vous devez revenir sur vos modifications appellez la commande git reset hard HEAD pour craser vos fichiers non commit s du r pertoire local par ceux du dernier commit Organiser son historique avec Git rebase Git est d un abord d routant Ses workflows s appliquent du contenu plut t qu des fichiers R sultat le travail de groupe et la gestion de diff rentes versions concurrentes d un m me contenu deviennent beaucoup plus simples Git effectue des commits atomiques il applique des lots de modifications sur un contenu souvent r parti sur plusieurs fichiers au lieu de g rer des fichiers proprement dits Il nous invite raisonner
115. vous avez dit Belle marquise vos beaux yeux me font mourir d amour Ou bien D amour mourir me font belle marquise vos beaux yeux Ou bien Vos yeux beaux d amour me font belle marquise mourir Ou bien Mourir vos beaux yeux belle marquise d amour me font Ou bien Me font vos yeux beaux mourir belle marquise d amour Commen ons par afficher la phrase d origine dans un terminal echo Belle marquise vos beaux yeux me font mourir d amour Belle marquise vos beaux yeux me font mourir d amour Il s agit maintenant d intervertir les mots de la phrase pour en cr er une nouvelle Pour une simple transposition on pourrait juger plus facile d utiliser awk awk ne g re en effet pas des lignes mais des champs d un enregistrement d une ligne d limit s par d faut par des espaces Autrement dit awk traite le texte comme une base de donn es Il peut facilement afficher toute la ligne ou seulement un ou plusieurs champs dans l ordre souhait Les champs sont indiqu s sous la forme n o n indique la position du champ dans la ligne partir de la gauche Ainsi indique le premier champ 2 le dernier etc 0 correspond toute la ligne Nous allons donc donner la d claration d amour de M Jourdain en entr e d un programme awk d une ligne gr ce au symbole de redirection pipeline echo Belle marquise vos beaux yeux me font mourir d amour awk print 9 8 TGT UEJU EL 52

version PDF - Processus de rédaction technique

Contents

Download Pdf Manuals

Related Search

Related Contents

version PDF - Processus de r&eacute;daction technique

Contents

Download Pdf Manuals

Related Search

Related Contents

version PDF - Processus de rédaction technique