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.