Pour bien rédiger en technique, il faut abaisser ses attentes [Article traduit]

1. L’écriture est une compétence essentielle pour les ingénieurs

   • L’écriture technique est indispensable à tous les niveaux de l’ingénierie, du message de commit à la documentation.
   • La différence entre bien écrire et mal écrire a un impact majeur sur l’efficacité du travail et la communication au sein de l’organisation.

2. Aussi concis et court que possible

   • Les lecteurs ne consacrent pas beaucoup de temps à un texte.
   • Si vous pouvez transmettre une idée en une seule phrase, faites-le.
   • Omettre volontairement certains détails peut au contraire être un avantage.
   • Placez l’essentiel au début du texte, dans la première phrase ou dans le titre.

3. Définir des attentes réalistes

   • N’espérez pas que les gens lisent un texte technique attentivement et le comprennent complètement.
   • Dans une organisation d’ingénierie, la confusion et les écarts de compréhension sont normaux, et l’écriture ne peut pas mettre tout le monde au même niveau.
   • En abaissant ses attentes, on communique au contraire plus efficacement.

4. Le but d’un texte est de transmettre clairement l’essentiel

   • L’objectif prioritaire est de faire passer à une équipe large un point très simple, comme « ajouter une configuration est complexe ».
   • Plus que d’amener une compréhension technique complète, il est important de fournir le minimum de contexte nécessaire pour inspirer confiance.

5. Ce qu’on peut réellement en attendre

   • Les destinataires d’un texte ont en général moins de connaissances de fond que son auteur.
   • À un large public, on peut transmettre un message simple ; à un très petit nombre, un contenu complexe de manière claire.
   • Le simple fait de souligner les points clés peut faire une grande différence dans une grande organisation.

6. Une pensée claire produit une écriture claire

   • Il est difficile de condenser un sujet que l’on comprend insuffisamment.
   • Reconnaissez les incertitudes et concentrez-vous sur ce que vous pouvez expliquer clairement.

7. Erreurs à éviter et bonnes pratiques

   • Ne vous obstinez pas à transmettre trop de détails.
   • Résumez progressivement ce que vous voulez dire à l’échelle d’une phrase, d’un paragraphe puis d’une page, afin de transmettre d’abord l’essentiel.
   • Même à des personnes ayant très peu de bagage technique, il est déjà précieux de transmettre le contexte général.

[yeobi222]

La vraie difficulté, c’est surtout de savoir comment intégrer des explications complémentaires pour faciliter la compréhension.
Quand la personne qui décide est étrangère au domaine, ou bien...

[girr311]

Cela s’applique non seulement à la documentation technique, mais aussi à la grande majorité des documents.