Variable dans un renvoi: elle a disparu!

Je travaillais sur un document à son début. Je n'avais pas encore importée mes variables et j'ai besoin d'une variable alors hop je magasine les variables pour ce document et je continue. J'ai un titre qui dit comment manipuler le (produit) alors je le change pour la variable "modèle" parce que ce document est le premier d'une série.

J'avais un renvoi à cette section et voilà qu'en rafraîchissant les champs (ctrl-A, shift-F9) l'endroit où j'ai mis la variable disparait!

Pas de panique, voici un petit truc pour dire à Word de prendre la variable en compte: mettez votre titre en "normal" puis redonnez-lui son titre au niveau que vous souhaitiez. Un F9 sur le renvoi va faire apparaître la variable. Par la suite, peu importe ce que vous choisissez comme valeur pour cette variable, Word suivra.

J'aime Word 2013

Un bel ajout que l'on voit dans d'autres logiciels, il apparait des lignes pour guider au moment de bouger une image dans un document Word 2013. Une image vaut milles mots :

Étapes 1 et 2, analyser et uniformiser

Mon projet ce mois-ci est de prendre un gros manuel de feux de signalisation temporaires, qui couvre tous les modèles de cette famille de produits et de le transformer en document maître avec des conditions. Le but est de lancer à partir de celui-ci la publication de plus petits documents pour chaque modèle, donc d'écrire dans un seul endroit les changements puis les publier pour tous les modèles. Et sauver des heures de travail en double et de réparation d'erreurs d'uniformité. Et je vais enfin essayer mon système à son plein potentiel.

D'emblée, avant de commencer le projet qui sera mon cas d'usage pour STC France et Lavacon, un plan d'action s'impose. Il est articulé simplement. J'ai écris les grandes lignes sur papier, puis au propre dans une feuille Excel. Ensuite j'ai assigné une onglet à chaque grand point.

Les grandes ligne en langage Ver-Mac
1) Imprimer les ASM (analyser)
2) Uniformiser
3) Audit de contenu
4) Document maître, déterminer les variables, les conditions, les nouveaux fragments.

1) Imprimer les ASM

En bon français, sortir les vues de dessins d'assemblages possible pour ce manuel. Aller dans notre base de données pour sortir les principaux modèles vendus et obtenir leur numéro de dessin. Le dessin est très utile pour savoir rapidement comment utiliser chaque modèle d'appareil et du coup de voir les similarités.

2) Uniformiser

Uniformiser les deux manuels anglais/français et les mettre à jour. "Code freeze", faire un PDF pour le soutien et les archives. Archiver le fichier Word.

3) Audit de contenu

Trouver ce qui est réutilisable pour les autres modèles. Il y a des remorques et des chariots, il y a deux types de contrôleurs tactiles, deux types de batteries, deux types de feux de circulation et j'en passe.

4) Document maître

Préparation terminée, le vrai travail commence! Les clés de décision pour les variables, les conditions et les fragments de texte sont décris dans cet article de pratiques sauf que cette fois il y a déjà une partie du travail accompli avec d'autres manuels. Il faut donc aller voir ce qui existe et le bonifier : importer les variables et voir si elles s'adaptent bien au nouveau manuel, ajouter des valeurs au besoin, ajuster les fragments de texte.

Les conditions devraient être déterminées par l'audit de contenu, mais je n'ai pas encore fait l'exercice concrètement.

Utilisation du plan d'action

Dans chaque onglet je note les ajouts, demandes et modifications. Par exemple dans l'onglet 1 j'ai trouvé de très vieux modèles de dessins, je devais décider quoi en faire s.il ssont encore en service.

Pendant l'uniformisation (onglet 2)  j'ai reçu une demande d'ajout au glossaire et j'ai ajouté une note de faire un chercher-remplacer d'un terme qui avait changé. Les questions sans réponse y sont consignées. J'ai mis une date de début et de fin pour suivre l'échéancier. Présentement le projet est presque prêt pour l'étape 3. L'uniformisation des deux documents de 100 pages a pris une semaine. Je n'ai pas pu résister à l'envie de mettre des fragments en mettant certains textes à jour. L'aidit commencera demain.

Un webinaire gratuit en français sur la rédaction AGILE dans Word.

Voici une conférence par Internet entièrement gratuite d’environ une heure sur la réutilisation de contenu directement dans Word, le jeudi 7 mai à 13h30. SVP, partagez.

L’hôte, STC France, est le « chapitre » Français de la société des communicateurs techniques, il n’y en a pas au Québec. C’est ouvert à tous ceux qui voudraient avoir une stratégie de réutilisation dans Word et aimeraient (même peut-être juste parfois, souvent secrètement) pouvoir le faire dans Word. 

Dans ce cas d'usage, il y sera discuté des besoins. Besoin d'être AGILE, besoin d'optimiser, besoin de faire tomber les silos, besoin de se servir de son expérience pour faire tout cela sans sous-traitant, sans perte de temps, sans courbe d'apprentissage rappelant l'Everest. 

Le comment dans ce cas d'usage sera discuté. Comment écrire des articles (snippets), comment faire des variables (planifier, localiser, essayer, recommencer) et appliquer des conditions, dans les deux langues, pour une multitude de modèles.

J’y ferai mon coming out au sujet de Word. Eh oui, j’aime Word. Je m’en sers tous les jours efficacement dans une équipe AGILE. Et j’adore cela.

https://www.eventbrite.com/e/inscription-cas-dusage-coming-out-jecris-avec-word-et-jadore-cela-et-vous-le-pouvez-aussi-16136230901

La même conférence sera diffusée en anglais en juin, par le même hôte.

Printemps agile!

Un peu de contexte...

Le printemps chez Ver-Mac est très intense en rédaction technique. Les DOT (department of transportation) et le MTQ, et autres ministères de transports au Canada et au É-U doivent boucler leur budget et préparer les mises en chantier. On voit les semi-remorques pleines de matériel qui arrivent et d'autres qui repartent pleines de panneaux à messages variables et plein d'autres produits, pour prendre le chemin de ces DOT.

Et c'est là aussi que ces gens demandent des options et des documents précis, c'est là que mon téléphone sonne le plus. J'adore cette période de l'année. On veut des manuels de pièces, on veut des documents à jour, on veut des documents personnalisés, on veut des nouveaux manuels d'opération pour des produits personnalisés.

Cette année, nous avons décroché une commande (entres autres) assez importante pour un projet très impressionnant sur la côte Est des États-Unis. La plupart des manuels nécessaires étaient à jour sauf pour deux modèle, qui nécessitaient des manuels de pièces et des manuels d'opération.

Se préparer pour les manuels de pièces

La rédaction agile ce sont pas que les outils, c'est aussi de trouver où simplifier les choses. Depuis plus d'un an nous travaillons sur les textes de la base de données afin qu'elle soit irréprochable, parce que ces textes sont réutilisés dans les dessins mécaniques et électroniques, qui aboutissent non seulement sur le plancher de production mais aussi dans les dessins techniques des manuels de pièces. Ils sont révisés par les ingénieurs, puis ils sont passés à mon service pour la révision linguistique. Nous avons terminé depuis un an tous les manuels de pièces pour deux grandes familles de produits. Conséquemment, la base de donnée de la voûte à dessin est révisée à au moins 70 %, mon temps de révision a diminué dramatiquement. Le niveau de la francisation est maintenant bien au-dessus de la plupart des compagnies.

Je fais les manuels de pièces dans InDesign en utilisant des variables. Les pages liminaires incluent une page titre, les textes de version, de mises en garde sur le manuel et notre garantie. 80% du texte est réutilisé donc les variables permettent d'avoir la plupart des pages en chapitres qui ne changent pas, il ne reste que l'introduction, parfois. Les autres chapitres sont des pages avec des titres pour chaque dessin et les pdf générés par les techniciens et ingénieurs. Ce sont les dessins qui ont été révisés préalablement.

Se préparer pour un nouveau manuel d'opération

J'ai maintenant plus d'une centaine d'article (snippets) écrits pour d'autres manuels, faire un nouveau manuel est très facile maintenant. J'ouvre Word et la barre de tâche de SmartDocs sur le côté. J'ouvre un document-maître d'un autre modèle similaire dans l'autre écran. Avec les noms des articles que je vois dans l'écran du document-maître, je peux faire une recherche par mot-clé pour chaque article, le glisser dans mon nouveau document et écrire seulement le nouveau contenu. Je vais chercher les variables, je les modifie selon le nouveau modèle.

Générer 110 pages de nouveau contenu en 3 jours (seule)

Ben pas tout à fait. Je ne fais pas les dessins c'est sûr. Même si des fois j'aimerais bien essayer.

Donc pour mon fameux contrat, je passe seulement une heure ou deux à réviser les dessins incluant deux passes de révision. Entre les passes je monte les structures dans InDesign. Puis toujours en attendant que la deuxième passe de révision des dessins soit appliquée, je fais le manuel d'opération, sécurité et entretien pour mes deux modèles qui sont des remorques-radar. Elles ont une remorque comme un modèle déjà passé dans SmartDocs, et des composantes générales assez similaires. Deux heures total par manuel avec une procédure de montage-démontage de l'appareil. Quand un article ne correspond pas tout à fait, je le convertis en Word standard et j'en fais un nouvel article pour une éventuelle mise à jour.

Conclusion

Avec les réunions et discussions pour réviser le contenu pour le comparer aux requis du client, toute la palette de documentation aura pris 3 jours. Pour moi c'est cela faire de la rédaction AGILE. Il faut savoir que je ne serais pas capable d'être aussi optimisée sans l'appui des différents services. Les ingénieurs comprennent bien l'importance de tout réviser les textes dans les dessins correctement et pousser les révisions dans la voûte même si c'est long au début car il y en a de moins en moins. Mon patron a été patient avec la conversion de mes manuels et il a parlé de mon système à la haute direction.

Je viens tout juste de recevoir le OK pour une famille de produits qui aura plusieurs petits manuels selon les modèles. J'aurai donc un gros document-maître pour chaque langue et je pourrai enfin utiliser des textes conditionnels pour lancer la génération de manuels selon les modèles. Et c'est ce projet que je compte utiliser pour mon cas d'usage dans un webinaire pour STC France en début mai.

Parce que bloguer, des fois, ce n'est pas assez

J'ai décidé de partager mon histoire ici pour d'autres collègues francophones qui souhaiterais être AGILE tout en restant dans Word. Le but étant d'être éventuellement capable d'échanger des trucs entre utilisateurs.

Pour étendre un peu mon rayonnement, j'ai décidé de tenter ma chance à LavaCon. C'est une conférence très prestigieuse pour les communicateurs techniques et ce fut une surprise de voir ma proposition monter en 7e position parmi une quarantaine de conférenciers.

Voici donc la conférence en question, en Nouvelle-Orléans, je sollicite votre appui, le titre est "Coming Out: I write in Word and I love It!"

Ma présentation est facile à trouver si vous choisissez "Crowdrank" à côté du bouton Filter, pas très loin sous la belle photo du "French Quarter". Elle se tient ne 7e-8e place normalement.

Cliquez sur Like sous ma présentation et tout ce qu'il y a à faire après c'est de choisir avec lequel de vos comptes sociaux vous votez : LinkedIn, Twitter, Facebook, Google+.

LavaCon 2015 Call for Speakers

View more lists from Jack Molisani

Attention aux variables variables...

Pourquoi c'est les patrons qui nous pincent à faire les pire gaffes? La mienne : prendre le champ Auteur pour le nom de la compagnie. J'y écrit systématiquement Signalisation Ver-Mac inc. Mais parfois dans ce champ le nom de la personne à qui la license de Word est attribuée y aboutit.

Je travaillais sur la garantie de nos produits. C'est un travail qui se fait avec la haute direction. Très contente d'optimiser ce document et d'en suite m'en servir en réutilisation intense, j'envoie un manuel version finale, avec la nouvelle garantie, sans regarder la garantie que nous avions révisée nombre de fois. Nous avions une rencontre dans l'après-midi avec un chef de service pour finaliser le tout. Voilà que mon téléphone sonne, et le nom d'une des 3 personnes les plus importantes de ma compagnie s'affiche. Il y a semble-t-il un problème avec le manuel! Voici ce qui apparait devant mes yeux dans la section de la garantie (cliquez pour agrandir) :

Guide de bonnes pratiques SmartDocs pour la rédaction technique en français

Depuis quelques semaines j'ai finalisé deux manuels avec SmartDocs, un de chaque langue. J'ai mis quelques notes de côté pour les ajouter au blogue puis j'ai commencé un autre manuel sur un autre produit et là j'ai découvert de nouvelles choses. Ma flèche devient un feu de circulation. Une, un. Ces deux petits mot on fait rallooonger mes notes, voici donc une ébauche de guide de styles et de bonnes pratiques auquel je vais revenir de temps en temps jusqu'au jour où je ferai peut-être un guide « pour les nuls » de SmartDocs en français.


Désolée, pas grand chose sur le texte conditionnel pour le moment, quand je vais en faire il y aura sûrement du texte à ce sujet.

Bonnes pratiques pour Word qui profitent en travaillant dans SmartDocs

• Pas de formattage d'un style, appliquer les styles seulement. Si un style ne fait pas, l'ajuster, le changement sera agile. Ce point est répété dans les Webinars 36 Office hours.
• Utiliser un gabarit de styles. C'est un document générique qui contient tous les styles utilisés et que l'on importe.

Pas mal moins long que tout ce qu'il faut savoir pour se servir de Frame et DITA...

Snippet ou texte conditionnel? (extrait d'une formation de SmartDocs)

Attention des fois on peut changer d'idée en cours de route.

Questions qui mènent à un snippet

• Est-ce que ce bout de texte sera réutilisé?
• Est-ce que d'autres peuvent en avoir besoin?
• Est-ce que je veux voir où ce bout de texte est utilisé?
• Ai-je besoin de plusieurs versions de ce texte?
• Est-ce que je veux inclure ce bout de texte dans un SmartFinder pour le sélectionner dans une liste préfiltrée de snippets?

Questions qui mènent à du texte conditionnel

• Est-ce que le bout de texte est spécifique à un modèle, une utilisation, un service, un modèle?
• Ai-je besoin de le montrer ou le cacher selon le type de document ou critères?
• Est-ce que je veux inclure ce texte dans un snapshot de document pour qu'il devienne partie d'un document standard?
• Ne pas oublier que les snippets peuvent être conditionnés.

Remarques plus spécifique à la rédaction en français

Préparer le plus grand nombre de variables à l'avance

Produit générique: les deux casses, et au pluriel. Par exemple, flèche, Flèche, flèches, Flèches.
Pensez au genre s'il s'agit d'un nom commun. Exemple pour les produits d'une compagnie de signalisation : une flèche, un feu, un panneau, une stèle-radar. En français, les variables on un genre et cela pose un véritable problème qu'il faut attaquer le plus tôt possible.

Exemple:
Dans mes snippets, mes produits varient en genre. J'ai un panneau, une flèche, un feu. Donc pour ma variable « produit générique » je dois avoir les expressions suivantes:
Produit générique seul: flèche, panneau, feu
Produit générique déterminé : la flèche, de la flèche, une flèche, d'une flèche, le feu, du feu, un feu, d'un feu, le panneau, du panneau, un panneau, d'un panneau.
Produit générique pluriel seul : flèches, feux, panneaux.
Produit générique pluriel déterminé? : les flèches, des flèches, les feux, des feux, ok on voit que sans genre on peut fonctionner comme en anglais.

Des variables possibles en vrac:
Nom de modèles
Compagnie au long
Compagnie au court
Année, année en romain, date
Version de manuel, de logiciel, de produit
Titre, type de document
--Surtout ne verrouillez pas les variables avant d'avoir fait plusieurs manuels et d'être absolument certain que la variable ne changera jamais. Si vous faites ce métier depuis un moment, vous savez que tout change, éventuellement.

Truc qui sauve beaucoup de temps de finition: Éditer toutes les propriétés du document Word pour ne pas avoir à le faire dans le PDF.

Bien regarder toutes les catégories dans Sharepoint avant d'élaborer le synopsys de votre manuel.

Pendant la rédaction

Rédiger le snippet en commençant par la langue de travail pour créer son titre dans cette langue. Utiliser SmartDocs pour chercher-remplacer un mot par une variable. Glisser-déposer les snippets, s'il s'agit du 2e, 3e manuel. SmartDocs 2014.1 permet de chercher dans les textes en plus des mots-clés. Le pied.

Révision

Faire la révision de toute une section jusqu'avant sa réutilisation (ex. tout un modèle, dans un manuel d'entretien avec plusieurs modèles), en sauvegardant les changements, sans synchroniser. Pas sûr(e) d'avoir enregistré tout? Dans Snippet manager, ceux qui ne sont pas encore enregistrés portent une étoile, on peut enregistrer à partir de cet endroit, actualiser, puis on est prêts à synchroniser. Quand la section est terminée, synchroniser d'un coup.

Pour un document qui a des snippets répétés à même le document, des onglets des grandes sections permet de savoir quand arrêter avant de dédoubler les changements, si vous faites le changement par une recherche-remplacement.

DITA... XML, XSLT? Consultants? Pas besoin.

De retour après quelques bugs

Travailler en français a ses aléas, j’avais une variable avec un accent (é) qui était utilisée, mais utilisée PARTOUT dans mon manuel. Ce petit mot 6 lettres a donné bien du fil à retordre à l’équipe de soutien. Étant rendue à bien au-delà de la centaine de snippets, ThirtySix Software a dû également penser à une méthode rapide pour faire la mise à jour qui serait compatible avec ma configuration de Sharepoint. Il y a autant de types de configuration qu’il y a de types de personnalités. Mais encore, il y avait une version qui était en développement donc les changements demandés ont été inclus dans la compilation. En parallèle, le boulot a apporté autre chose donc la mise à jour a été appliquée à sa sortie en début février puis deux ou trois semaines plus tard j’ai réussi à corriger les snippets problématique selon la méthode envoyée en mi-février.

Aujourd’hui, j’ai ouvert le manuel des flèches en anglais. Un snippet a donné un message d’erreur auquel je ne m’attendais pas du tout, pour découvrir qu’il n’avait pas de langue assignée dans les propriétés. On aurait dit que plus rien ne marchait. J’ai donc suivi une démarche méthodique :

• Vérifier que tout est archivé dans Sharepoint.
• Vérifier que tous les fichiers ont des propriétés dûment remplies dans Sharepoint.
• Vérifier l’état des snippets dans Word, synchroniser.
• Régler tous les problème des snippets identifiés par le gestionnaire de snippets du ruban de SmartDocs.

Maintenant tout était vert (OK) partout. J’ai alors passé au document en français avec la même méthode et je suis enfin sortie du bois.

Je vais donc prendre un peu de temps cette semaine pour faire le point. Il y a eu un webinar donné par ThirtySix Software sur la préparation de contenu, on peut l’avoir en version téléchargée. C’est dans la liste pour faire le point.

Prochaine entrée : mon propre guide de style SmartDocs.

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.