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!