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.