Réviser un document AGILE, wow

Qu'est-ce qu'un snippet?

Les snippets, c'est des fragments de document que l'on peut réutiliser ailleurs. Par exemple, la garantie peut en être un, qui contient les variables Nom_de_compagnie et parfois Nom_de_produit. Ou une procédure pour nettoyer un panneau solaire, avec une variable Produit qui change selon le manuel. On construit donc un document en insérant des snippets, puis on choisit le contenu des variables quand elle ont plusieurs possibilités (produit).

Il y a des variables qui sont là également pour l'uniformité et qui ne change que très rarement. Le nom de compagnie, par exemple. Je mets Ver-Mac dans une variable que j'appelle company_short. Si jamais notre directeur au marketing dit « Johanne je préfère toujours voir Ver-Mac inc. », hop,  je vais le changer dans cette variable. Si j'ai bien pris soin de prendre la variable chaque fois que le nom de compagnie a été rédigé dans les textes des snippets, le nom de la compagnie sera correct dans toute la documentation de Ver-Mac d'un seul coup, avec la bonne typographie. Les variables sont utilisées dans Frame et InDesign, rien de nouveau ici. Mais, maintenant Word l'a aussi, c'est chouette, elles offres listes déroulantes et sont entreposées dans Sharepoint pour servir partout.

Montage des snippets, quelques découvertes

Pendant la préparation des snippets (fragments de texte), on peut constater rapidement quelques petits points:
-Il est important de bien nommer les fragments de textes, ce sont les mots-clés pour les trouver rapidement par la suite.
-Un plan de réutilisation est nécessaire avant de commencer parce que même en connaissant bien les produit on peut faire des erreurs. Ce que j'appelle un plan de réutilisation, c'est tout ce que l'on voit en commun qui sera réutilisé. Ce plan peut prendre forme pendant ou juste après l'audit de contenu.
-Il est préférable de faire une liste de variables d'avance.
-Il faut se préparer à changer d'idée en cours de route facilement. Autrement dit, pendant que l'on monte notre structure, toujours se demander si ce serait facile de changer d'idée, à chaque étape. Penser AGILE, c'est d'être flexible.
-Il faut vraiment bien connaître son Word pour être méthodique et il faut aimer Sharepoint; ou confier la configuration à SmartDocs et utiliser leur Sharepoint dans le nuage.

Les fonctionnalités que j'ai adorées dans SmartDocs:

• Le search-replace des mots pour des variables, fantastique.
• Comme un spectacle, regarder les snippets synchroniser quand je change ou ajoute un mot. Il change tout seul dans tout mon document de 200 pages ou le snippet est utilisé. C'est le pied.

La révision

Ce qui me mène à la révision. Après avoir transformé mon bureau en machine à snippets,  le document est monté selon les exigences, il est maintenant temps de commencer la révision. Plusieurs changements au niveau de la sécurité et des opérations ont été demandés et bien sûr, pendant l'exercice de montage, des textes désuets ont été relevés.

Tel que susmentionné, j'adore la synchronisation.

Dans cette boîte de dialogue je vois les snippets à synchroniser quand je viens d'aller porter une version plus récente ailleurs dans le document. Le même snippet ailleurs dans le document ne se met pas à jour si je ne l'ai pas demandé. Je vois la page où il loge, son numéro de version et si quelqu'un l'a sorti dans Sharepoint pour le modifier (check out).

Hier, j'ai mis des légendes numérotées automatiquement dans quelques snippets. J'ai synchronisé. J'ai parcouru mon document et voilà, les bouts de textes exactement pareils ont le bon numéro de figure. C'est tout.

Les devoirs, et un premier mandat officiel

Note pour les amis Européens : le ton de ce blogue est informel. Le lectorat du vieux continent augmente, mais ce blogue ne changera pas de style, à vous de vous laisser charmer!

On s'étaient entendus avec mon patron de commencer avec les feux de circulation pour l'audit et le premier vrai produit. Sauf que le 11 octobre, mon patron me rencontre et me dit que je dois immédiatement me concentrer sur nos flèches. Alors je suis tout aussi contente car du côté des flèches c'est un produit avec un très fort taux de réutilisation de contenu. La formation est toute fraîche donc on va faire nos devoirs de formation... avec la flèche.

Je finis le dossier en cours et je commence à faire un plan de travail. C'est vraiment le plus difficile, préparer un plan. Tout est possible. Je me concentre sur ce qui est similaire, et de quelle façon le réutiliser. Le 18 je rencontre enfin les SME pour connaître leurs attentes. La démarche faite pour le mock-up et que j'avais l'intention d'appliquer était de faire un document maître avec des "builds" multiples. À ma grande surprise, on demande un seul gros livre.

Le défi est génial : nous avons 4 grands types de flèches, on veut faire 4 grandes sections dans le même livre, où le client trouve tout ce qu'il a besoin pour sa flèche dans cette section. La solution d'indicateurs de couleur sur les côtés est choisie pour les grandes sections, ce qui donnera un indice de notre section autant en version papier qu'en PDF. La réutilisation se fera donc à même le seul document, synchronisation rapide!

La réutilisation en gros:
-Une flèche remorquée a deux types mais la même remorque.
-La structure qui supporte la flèche est du même type pour trois flèches sur 4.
- Il y a des panneaux solaires et des batteries pour 3 des quatre types.
- Il y a un contrôleur tactile pour tous que l'on veut répéter dans chaque section plutôt que de faire un manuel à part.

Je dois quand même faire des fragments de documents, les snippets, et les variables, mais pas de texte conditionnel dans ce livre puisque je ne fais pas de "builds".

Au niveau des catégories de métadonnées créées dans Sharepoint et qui génère des listes déroulantes dans Word quand je fais des snippets, j'ai eu à ajouter des nouvelles lignes donc retour dans la formation. Ça donne une certaine fierté de pouvoir fouiller dans certains coins assez creux du CMS.

Première formation

À propos des besoins

Je crois que j'en ai pour mon argent, vraiment. Oui on achète Office au complet pour ce prix-là mais dans les outils spécialisés, faut chercher longtemps pour trouver une application qui fait exactement ce que l'on a besoin. Mais avez-vous bien DÉFINI votre besoin au départ? On achète pas une Cadillac pour aller au restaurant du coin, à moins d'avoir quelque chose à prouver et faire preuve d'uns conscience écologique de la taille d'un petit pois. D'une graine de lin, dit-je.

Préparation à la formation

Ce matin, j'avais ma première formation (sur 4 heures) et je ne savais pas du tout à quoi m'attendre. En plus, mon ruban de SmartDocs avait disparu et mon document sur lequel j'avais simulé un manuel avait perdu toutes ses "étiquettes" de texte. J'avais constaté des problèmes mais étant en pleine période de développement dans l'équipe de R&D, pas le temps de trouver une solution.

Jennifer de SmartDocs m'avait envoyé deux documents à remplir qui étaient un genre de préparation, un atelier de travail. Il y avait un document pour décrire notre Sharepoint et un autre, un questionnaire, pour définir comment la documentation se divise à l'interne. L'exercice permettait de diviser plus facilement les sujets dans les différents services de la compagnie (ou départements, pour prendre un calque).

Here we go!

Donc me voilà connectée dans Webex avec mon word dépourvu de ruban SmartDocs. Je me retrouve avec non pas une mais 3 personnes, c'est-à-dire Lisa que j'ai rencontré à Atlanta et qui m'a parlé de sa solution, Jennifer qui donnerait la formation et une autre femme en formation qui venaient nous écouter. Elles se sont mises ensemble pour me "débugger"et ç s'est passé assez rondement parce que dans les temps morts Lisa attaquaient mes questions.

Nous avons ensuite passé à l'application de la structure que je m'étais montée dans le questionnaire. C'est un beau plongeon dans Sharepoint et même si l'introduction d'un accent (é)  a causé une autre petite difficulté (qui a été réglée par un certain Bryan) j'ai trouvé ce petit stop très instructif car nous sommes retournés plusieurs fois changer des options, j'ai donc bien assimilé le contenu. J'ai déjà ajouté une colonne dans Sharepoint mais jamais avec un gabarit sur mesure qui a un impact dans Word. Le résultat donnait deux autres menus déroulants dans Word, quand j'ajoute un bout de texte dans mon entrepôt Sharepoint par le biais de SmartDocs. J'ai bien aimé ce petit plongeon et je vais retourner voir cet endroit car je veux faire ma première famille de produit avant le prochain cours. Je suis certaine que l'exercice va provoquer des ajustement dans la sélection de sujets.

Comme je mentionnais plus haut nous avons attaqué mes questions également, ma plus grande question étant comment coder des langues. J'aimerais bien avoir les deux langues dans le même document maître, les trois quand c'est le cas. Lisa a pris le temps de me demander ce que je voulais faire avant de me proposer quelques pistes de solutions. Une de mes craintes était que si je mettais les deux langues j’obtiendrais un beau fouillis de couleurs à cause des textes conditionnels selon les langues. Mais on peut enlever les couleurs et en plus, on peut faire un "snippet" conditionnel.

Les devoirs

L'équipe de support a mis sur pied des formations gratuites et je me suis inscrite à un webinar sur les variables de 1h30 la semaine prochaine. Aussitôt que la doc sur mon projet en R&D est stable j'attaque mon premier projet. Il faut battre le fer tandis qu'il est chaud!

Inventaire

Par curiosité hier j’ai fait un inventaire des manuels, très instructif. Les boss aiment les métriques donc j'ai également envoyé mon bilan à mon patron. Il faut noter que je fais tout cela à travers la poutine, sauf quand je reçois un mandat officiel pour la prochaine étape. 

L'inventaire

Nous avons 4 grandes familles de produits, plus une autre de petits produits que l'on appelle utilitaires. Ça donne dans ma documentation officielle 42 manuels entretenus dont la moitié de 30 à 90 pages et 24 autres documents comparable qui sont disponibles mais ne sont plus entretenus. Il y a une dizaine de manuels en chantier et 4 nouveaux dans la liste à venir. Ça fait quand même beaucoup pour une rédactrice solo.  

Piste de solution

Nous avons acheté SmartDocs. Je vais avoir une formation. Beaucoup d'information a été donné à la compagnie et ils vont préparer un formation sur mesure. Avec ce système AGILE, je pourrais viser 1 doc maître pour chacune des 3 grandes familles et un pour notre logiciel. Ensuite je pourrais regarder les utilitaires pour les brancher dans les manuels maître qui ont des similitudes, par exemple une stèle radar a une remorque semblable à celle de notre flèche.

Ça donnerait comme résultat une douzaine de documents maître qui génèreraient possiblement environ 45 documents personnalisés (customisés comme dirait un Français) en anglais, le français en a 19 actuellement pour 4 familles de produits, donc 4 documents maîtres en français. J'aurais donc environ 20 documents maîtres à ouvrir mais ces documents maîtres ont entre eux également beaucoup de réutilisation, j'estime le travail d'entretien à l'équivalent d'une douzaine de manuels total qui génèreront environ 60-80 documents personnalisés selon les modèles et les options grâce à la flexibilité dont je disposerai pour construire mes manuels. J'ai estimé l'économie de temps à 50% à mon patron, il faut penser au temps qui a été consacré à l'audit et l'apprentissage.

L'audit

Pour la prochaine étape de l’audit de contenu, je pensais prendre par produit, mettons le panneau à message variable, avec un tableau, et cocher quand un morceau de texte relevé appartient aussi à un autre produit. Exemple une procédure de chargement des batteries va être cochée dans pratiquement tous nos produits. D'un audit de produit à l'autre, l'audit sera moins long. J'ai donc demandé une autre rencontre à mon patron pour brasser tout ça.

Premier jalon... Outil choisi

Petit retour sur l'audit de contenu.

Une grosse lacune de Windows, c'est d'être incapable de transformer un résultat de recherche en fichier excel. Et bien pour le prochain audit de contenu, je vais utiliser Acrobat Pro, il permet des recherches assez poussées et on peut les transformer en .csv. Après suffit d'être ferré en excel ou se faire un ami ferré pour avoir un fichier excel trié de plusiers façons possible.

On passe aux choses sérieuses!

Aujourd'hui se termine mon évaluation de SmartDocs. J'ai ADORÉ mon expérience, et je le recommande chaleureusement à tout rédacteur qui résiste encore et toujours à FrameMaker.

J'avais besoin d'un livrable. Mon patron m'a sagement conseillé de faire un "mock up", un faux document, pour essayer la solution que j’envisageais. SmartDocs propose un ruban supplémentaire dans Word avec des barres sur le côté (task panes) qui permettent de basculer entre les différents items spéciaux. Il y a des snippets (bouts de textes), des variables et des textes conditionnels et on lance ultimement une tâche en batch pour construire tous les manuels que l'on souhaite selon les critères définis dans les variables et les textes conditionnels. C'est plus long à expliquer qu'à faire.

J'ai mis environ une journée à faire le tour du didacticiel. J'ai ensuite mis deux jours pour faire un "mock-up" en partant de notre structure de manuel. Un document de ce genre fait environ 90 pages, j'ai omis une section d'une douzaine de pages, le document maître qui contient tous les textes possibles fait environ 50 pages. J'ai fait plein de snippets avec les précautions de base, des textes conditionnels avec les procédures et j'ai définis 4 modèles également en texte conditionel. J'ai mis des variables pour le type de document, les versions, les années. J'ai fait 6 tâches de construction de manuel, chacun pour sortir en word et en pdf.

Les documents résultants étaient presque à mon goût au premier essai et puis que c'est un mock-up j'ai arrêté l'effort là. Fut-ce un vrai manuel j'estime le peaufinage aurait été chercher une autre heure. J'ai ensuite fait un démo à mon boss de ce résultat, bon bilan, plein de bonnes questions.

 

Sharepoint

Un peu moins drôle, configurer Sharepoint, parce que je ne le connais pas en tant que spécialiste réseau mais plus en tant qu'utilisatrice. J'ai envoyé le guide de configuration de Sharepoint pour SmartDocs à notre gentil TI. Environ une demie-journée d'échanges entre le support de SmartDocs, moi et notre TI pour découvrir que nous étions configurés en français de France et non Canadien français, nous voilà ensuite avec les bons gabarits.

Puis on me passe les rennes pour configurer le site et l'entrepôt de données dans Sharepoint, dans le coin juste pour cela que le directeur de l'informatique a conçu. Une chance qu'il a réussi à me donner des minutes de temps en temps. Sharepoint est un monde à part. J'ai trouvé l'expérience un peu éprouvante mais il faut s'adapter, dans mon milieu de travail on tombe souvent dans des mondes à part... (musique des X-File). Hier j'ai commencé à transférer quelque snippets du site Sharepoint de SmartDocs vers mon coin à moi et ce matin démo au patron et au directeur du marketing. Ça marche sur toute la ligne.

Conclusion de l'essai d'outil

Ben on achète, avec 4 heures de formation. Il y a encore plus d'options à explorer comme les Smartbuilders et les Smartmarkers. Ce sont des macros de luxe en gros, le genre de chose que j'ai déjà essayé de faire sans grand succès.

Autre point, le soutien technique de SmartDocs a été génial, leurs documents assez bien faits et il m'ont donné une semaine de plus parce que deux semaines c'était trop court.

Quand on autorise la collaboration dans Sharepoint, les snippets peuvent être modifiés sans avoir le logiciel. Je n'ai pas encore étudié comment approcher les langues. Vu que c'est construit avec des principes de programmeurs, je pourrais faire un diner "lunch'n learn" avec mes collègues pour échanger des idées.

Prochaine grosse étape : audit de contenu pour un premier manuel. Prochaine entrée probablement sur la formation.

Essai d'un outil

En rédigeant un petit résumé de l'audit de contenu « pilote » à mon chef d'équipe, je sens que j'ai besoin d'un livrable maintenant.

Je lui ai soumis l'idée de cibler un produit simple, l'auditer, installer une version d'évaluation de SmartDocs et compiler les 6-8 manuels possibles qui font 20-30 pages chaque. J'ai l'appui de notre TI pour me faire un espace Sharepoint et j'ai contacté un concurrent de SmartDocs, Intelledocs, pour voir comment ils approchent un monde manufacturier comme le nôtre, avec la rédaction technique réalisée par une seule personne.

Audit de contenu pilote

C'est fait, un premier audit de contenu. Pratiquement tous les appareils utilisent des batteries que les panneaux solaire rechargent, donc les batteries furent le thème. Un de mes bloquants majeurs semble un petit détail mais il est très irritant : quand on fait une recherche dans Windows, on ne peut pas convertir rapidement le résultat en fichier Excel. Il faut passer par DOS! Nua avons quand même procédé en pensant de trouver une solution le plus vite possible pour ne pas perdre la liste de ce qui a été audité.

Préparation 

Ma collègue a sorti une liste de document suite à une recherche dans notre bibliothèque réseau de documentation officielle. Elle l'a imprimée. Ayoye mon écolo, environ un empan de hauteur, toute une pile.

Méthode

• Nous avons pris des surligneurs oranges et nous avons surligné toutes les itérations du mot batterie ainsi que les sujet possiblement réutilisables qui touchent les batteries. 
• Nous avons mis le total d'itération sur la page couverture.

Conclusion

La démarche a pris environ une demi-journée à deux. Ce fut très instructif mais il ne sort pas vraiment de livrable de cet effort, seulement une méthode. Je crois cependant que nous sommes prêts pour faire un 2e audit avec une famille de produit entière. En attendant, ce qui a été récolté doit être entreposé quelque part. Pour ce faire, je vais discuter Sharepoint avec nos TI.

Prochaine étape : essayer SmartDocs?

Baby Steps vers AGILE

Bienvenue dans mon blogue professionnel.

J'ai eu plusieurs blogues, jamais pour le travail. Ces blogues m'aidaient à épancher ma soif d'écrire sur tout. Mais voilà, après 15 ans en rédaction technique, je me prépare pour un gros changement. J'ai besoin de partager ce changement parce que je tend vers un chemin que la plupart des rédacteurs ne prendrons pas. Je veux tenir un journal pour ceux qui oseront tenter la même chose.

AGILE

Ce que je retiens d'agile pour nous les scribes, c'est éliminer l'inutile et ajouter ce qui est un plus pour les utilisateurs, seulement. Pis suivre à la même vitesse que les sprints ! Hiha...

Note pour mes amis néophytes: Agile est une méthode de travail. Elle ressemble à la méthode Toyota.

POURQUOI AGILE

Depuis 15 ans ça fonctionne très bien avec ce que j'ai appris et appliqué. Et me voilà dans une compagnie qui a beaucoup de produits, pas assez de doc et une quasi carte blanche dans une équipe agile. C'est inspirant mais je ne suis pas très à jour dans mes connaissances.

Donc après un an sur place on m'envoie à un congrès de rédacteurs techniques de la société des communicateurs techniques (STC) à Atlanta. Je passe 3 jours avec environ 200 autres communicateurs techniques. C'est très inspirant sauf qu'ils sont dans FrameMaker et je suis dans Word, les conférenciers nous parlent de DITA mais les outils sont loin d'être pour le commun des mortels. On nous dit qu'il est temps pour nous d'apprendre le XML. Mais je ne suis pas d'accord! Je ne veux pas manquer de respect envers tout ceux qui choisissent Frame et le XML, je suis seulement étonnée que tout le monde finisse par là. Je suis sceptique et perplexe devant ce mouvement de masse vers une solution trop lourde, trop chère et trop difficile. J'ai beaucoup appris et je retourne au bercail avec des rencontres précieuses et des connaissances à approfondir.

Ma seule conclusion concrète est l'audit de contenu. Peu importe le chemin choisi, je veux prendre le chemin agile et il passe par un audit de contenu. En attendant de peut-être trouver une solution conviviale pour faire du XML sans faire un bac en informatique, je vais me concentrer sur le début et prendre des conseils autour de moi.

Prochain article : mon premier pilote.