La page blanche : une histoire d’horreur en trois mots
Comme je l’ai mentionné dans mon article sur la livraison continue, mon objectif en tant que rédacteur technique est d’amener autant d’experts que possible à rédiger leur propre documentation. Titiller leur intérêt n’est pas si difficile, les experts sont généralement passionnés par leur domaine et excités à l’idée de contaminer tout le monde. Mais une fois qu’ils commencent réellement à essayer d’écrire du contenu, c’est souvent la douche froide. Quand je leur demande ce qui ne va pas, la réponse est presque toujours la même : “Je ne sais pas par où commencer.”
Ce problème est tout à fait normal. Vous avez une bonne idée de ce qu’il faut couvrir, vous avez discuté avec les ingénieurs et les experts, vous avez passé au crible les tickets de la hotline pour trouver les points qui coincent le plus souvent, vous avez bien fini tous vos devoirs, il n’y a plus qu’à se lancer. Mais là, c’est le drame. La page reste vide, le curseur clignote comme pour se moquer, et plus vous regardez l’écran plus vous vous demandez si vous n’auriez pas plutôt dû faire vendeuse de gaufre ambulante.
Ça arrive à tout le monde, y compris à moi dont écrire de la doc est le métier depuis des années. Pas de panique, j’ai une solution.
Les sujets comme cadre
N’ayant jamais été capable de faire une gaufre correcte de ma vie, j’ai développé une stratégie de contournement. Heureusement pour moi, l’outil de rédaction de contenu avec lequel je travaille utilise des topics. Il n’est pas DITA à proprement parler, l’objectif de l’outil étant d’être plus léger, plus souple et plus simple à utiliser qu’une solution XML, mais c’est certainement de là que vient l’inspiration. Et bonne nouvelle, les topics font un modèle d’écriture tout à fait robuste !
Pour faire court : notre outil, edc, peut créer plusieurs types de documents, aussi appelés stratégies. Modes d’emploi, FAQ, entrées de glossaire, document théorique et ainsi de suite. Chaque stratégie a des topics associés.
Les topics de base fournis avec le produit sont About (À propos), Prerequisites (Prérequis), Usage (Utilisation), Exemple, Pièges à éviter (Pitfalls), Définition et Théorie (vous pouvez en créer plus si nécessaire). Ils répondent chacun à un besoin ou à une question spécifique.
Si j’écris une FAQ, je n’aurai besoin que de Usage et éventuellement de About. Si j’écris une entrée de glossaire, je n’ai besoin que de Définition. Pas besoin d’y réfléchir, il suffit de glisser et déposer le topic et de lire son nom.
Pour les documents simples, restreindre la liste des topics vous empêche de vous éloigner trop du sujet. Les documents plus longs sont un peu plus compliqués : on ne peut pas utiliser les topics pour restreindre, mais on peut toujours les utiliser comme guide.
Si vous ne savez pas comment trier toutes ces belles informations que vous avez recueillies, utiliser la liste des topics dans l’ordre où ils sont fournis est une solution parfaitement valable.
- À propos : à quoi sert la fonctionnalité ? Pourquoi l’utiliser ?
- Prérequis : faut-il avoir fait quelque chose de spécifique avant d’utiliser la fonctionnalité ?
- Utilisation : des instructions sur la façon d’atteindre l’objectif de la fonctionnalité
- Exemple : insérez une capture d’écran de ce à quoi devraient ressembler les résultats si vous suivez correctement les instructions
- Pièges : dépannages et conseils divers
- Théorie : les éléments scientifiques, pour les utilisateurs férus de mathématiques qui veulent savoir comment la fonctionnalité marche exactement (la plupart de nos clients sont des géologues et des géophysiciens, nous l’utilisons donc plus souvent qu’on ne pourrait le croire).
Ce cadre couvre solidement les bases dans un ordre logique. Aucun des sujets n’est obligatoire, donc si l’un d’entre eux ne vous concerne pas, il suffit de l’omettre. L’outil est conçu pour de l’aide utilisateur de logiciel, mais vous pouvez absolument utiliser le framework sans l’outil. Observez :
Comment faire des crêpes, ou les topics appliquée à un sujet du quotidien
À propos
Une crêpe est une sorte de gâteau très fin cuit à la poêle. Il est généralement servi avec une garniture sucrée comme de la confiture ou du Nutella.
Prérequis
Avant de commencer, rassembler les ingrédients suivants :
- 300g de farine de blé
- 3 cuillères à soupe de sucre en poudre
- 60cl tasses du lait de votre choix
- 3 œufs moyens
- 70g de beurre
- 2 cuillères à soupe d’huile végétale
- rhum ou de vanille, pour parfumer
- un pincée de sel.
Utilisation
- Faire fondre le beurre.
- Dans un grand bol, placer tous les ingrédients sauf le lait.
- Versez lentement le lait en fouettant doucement.
- Continuez à fouetter jusqu’à ce que la pâte soit lisse et sans grumeaux.
Elle doit être fluide mais suffisamment épais pour enrober une cuillère. - Laisser reposer la pâte au réfrigérateur pendant au moins 10 minutes, jusqu’à une nuit.
- Sur feu doux, graisser une poêle antiadhésive avec du beurre ou de l’huile.
- Versez juste assez de pâte pour couvrir complètement le fond de la poêle.
- Une fois que la surface de la crêpe est pâle et matte, retournez-la pour cuire l’autre côté.
Le côté cuit doit être doré et de couleur uniforme. - Au bout de 30 secondes, retirez la crêpe de la poêle.
Le deuxième côté doit être pâle, parsemé de petites taches sombres. - Réserver sur une assiette et couvrir d’un torchon propre jusqu’à épuisement de la pâte.
Exemple
Ici, vous pouvez voir l’aspect différent des deux côtés d’une crêpe.
Présentation courante des crêpes : tartinées de confiture ou de Nutella puis pliées en triangles.
Pièges
La pâte peut encore avoir des grumeaux après avoir été fouettée. Ne pas utiliser la pâte telle quelle, les grumeaux impactent négativement la texture de la crêpe.
Pour éliminer les grumeaux, passer la pâte brièvement au mixeur ou la filtrer avec un tamis fin. Si vous utilisez un mixeur, laissez reposer la pâte plus longtemps. L’appareil peut aérer dans la pâte, les bulles ont besoin de temps pour remonter à la surface et éclater.
