DITA Boot Camp : une semaine en Pennsylvanie

La semaine dernière, j`ai eu l`occasion de participer au DITA Boot Camp à Warrendale en Pennsylvanie, à une vingtaine de minutes en voiture de Pittsburgh.

Pour ceux qui ne connaissent pas le langage DITA, on peut le résumer à une nouvelle norme XML dédiée à la documentation technique.
Dans celle-ci la documentation devient granulaire et chaque contenu est décrit en sujets, topics (tasks, concepts, référence) avec des tâches, normes … Le but est que la documentation soit réutilisable, peut être localisée vers d`autres langues très rapidement. Le passage à la norme DITA permet à nombre d`industries de gagner prés de 50% en productivité, voire 200% en localisation (traduction) et par la même des milliers, millions de dollars.

Le passage d`une documentation à cette norme prend entre une et deux année et représente un grand changement au sein de équipes de rédaction technique. Initié par IBM de puis 2004, de grandes entreprises : Nokia, Boeing, US Postal, AMD, Sybase … sont passés à cette norme.

Le Workshop s`est très bien passé, une organisation parfaite et un rythme intensif, de 8h30 à 16h30 avec une pause lunch américaine de 15 minutes-20 minutes.
De part la présence dans la salle de participants, consultants, avec des accents sud-africain, australien, de l`Illinois, Texas, Ontarien … il ne va pas sans dire que l`avant dernier-jour je ressentais un peu de fatigue

J`ai eu l`occasion de visiter une fin de journée Pittsburgh grâce à George, un ami du réseau
Couchsurfing. Il revenait la veille d`un voyage à Los Angeles chez ses parents et lundi devait reprendre le travail et préparer des cours ; mais a été d`une gentillesse extrême pour me montrer le centre-ville, le grand stade … et déguster de bon tapas.

Puis vendredi direction Montréal, après un aller par Cleveland et des retards, le retour s`est très bien passé par Detroit.

Lien vers l`album Flickr

DTD et XML hiérachisation

Lorsque qu’on construit une DTD à partir de fichiers XML existant, on se rend compte que la hiérarchisation des parents/enfants est essentielle. Je parle à travers les structures de déclaration pour permettre une meilleure lisibilité du code.

Plus que les commentaires, cet aspect est primordiale pour une relecture par un tiers.

Si on se réfère a de nombreuses documentations on se rendra compte que le code est souvent entassé en 2 parties, on déclare tous les éléments puis les attributs le sont dans une seconde partie.

Le problème est que si cette méthode est claire avec 2 éléments d’une DTD, il suffit d’avoir un fichier XML complexe avec de nombreux enfants pour être perdus.

J’ai été confronté a dresser une liste de DTD récemment a partir de fichier XML de plusieurs 10 dizaines de lignes, voire centaines.

La première chose est de dresser de décrire l’arbre DOM avec le parents et enfants et les attributs
Pour la lisibilité autant colorier l’ensemble. Dresser l’arbre DOM c’est un peu faire du mind-mapping

En regroupant les parents et les enfants avec attributs ATTLIST  en dessous, il est plus facile de lire le code que de faire une description des éléments puis les attributs dans un autre bloc sous-jacent

<!ELEMENT type (#PCDATA)>
<!ELEMENT statuses ((cycle+))>
<!ELEMENT states ((state+))>
<!ELEMENT state ((lockable, nextStates)?)>

<!ATTLIST cycle
collection CDATA #REQUIRED
description CDATA #REQUIRED
initial (true | false) #IMPLIED
lastworkcycle CDATA #FIXED “false”
level CDATA #FIXED “0″
name CDATA #REQUIRED
type (formatted | deleted | catchall) #REQUIRED>

Ensuite on pourra parser l’ensemble dans 2 validateurs XML Oxygen ou Stylus par exemple.