Ce à quoi je pense quand j’édite (2019)

 (evaparish.com)
2 points par GN⁺ 2024-04-07 | 1 commentaires | Partager sur WhatsApp
  • L’édition consiste, avant de polir les phrases, à vérifier ce que le texte cherche réellement à dire et à qui il s’adresse ; les mêmes principes de base peuvent s’appliquer aux e-mails, documents, blogs et romans
  • Rappeler le point essentiel au début et à la fin du texte, et ajouter un nom plutôt que d’utiliser seulement des démonstratifs comme « this/that », aide le lecteur à ne pas perdre le contexte et améliore la clarté
  • Réduire les mots inutiles, transformer les consignes en impératif, et découper les longues phrases ainsi que les structures en « of/for » permet de transmettre le sens plus rapidement
  • La voix passive, les adverbes, le jargon et les clichés peuvent brouiller l’auteur de l’action, le sens exact et le périmètre des lecteurs ; il vaut donc mieux les remplacer par des verbes et des explications concrets
  • Une bonne édition ne consiste pas à suivre aveuglément des règles, mais à être conscient de ses choix de langue en fonction du message à transmettre et à supprimer les formulations inutiles

Commencer par définir ce que le texte dit réellement

  • Avant de passer à l’édition phrase par phrase, il faut d’abord vérifier que le texte dit bien ce qu’il était censé dire
  • Rédiger un préambule (preamble) personnel pour chaque texte permet de disposer de critères d’édition
    • Les questions essentielles sont : « quel est le point principal ? » et « pour qui écrit-on ? »
    • Notez ces informations tout en haut du document, puis comparez-les au contenu réel pendant la rédaction et l’édition
  • Si vous ne pouvez pas résumer l’idée d’un billet de blog en une ou deux phrases, il sera difficile d’écrire un texte cohérent
  • Dans les cours d’écriture créative de Writers Studio, chaque devoir comprend un préambule indiquant le narrateur, le ton et l’atmosphère visés, et l’évaluation se concentre davantage sur la technique et l’atteinte de l’intention que sur les préférences personnelles

La répétition est un dispositif qui garde le lecteur accroché

  • Même si le point principal paraît suffisamment clair, le redire au début et à la fin du texte aide le lecteur à mieux suivre l’argument
  • Un tutoriel de documentation fonctionne généralement bien lorsqu’il présente ce qui va être fait, fournit la procédure, puis vérifie que l’exécution s’est bien déroulée
  • Un billet de blog gagne aussi à présenter le sujet traité, à le développer dans le corps du texte, puis à se terminer par un bref résumé
  • La répétition est également nécessaire au niveau de la langue
    • Ne vous contentez pas d’utiliser les pronoms démonstratifs « this » et « that » : ajoutez un nom indiquant ce qu’ils désignent
    • « To solve this shortage » est plus clair que « To solve this »
    • « Successfully authenticating will take you to the home screen » est plus explicite que « That will take you to the home screen »
  • Ce qui peut sembler répétitif à l’auteur devient, pour le lecteur, une clarification qui facilite le suivi du texte

Simplifier : retirer les mots qui n’apportent pas de sens

  • La tâche la plus importante de l’édition consiste à supprimer les mots qui ne contribuent pas au sens
    • « You will need to run this script » peut être réduit à « Run this script »
    • « You can aid in readability by making sure… » peut être réduit à « Make sure… »
  • Sauf raison particulière, il faut arriver au point principal aussi vite que possible et éviter d’enterrer le sens sous un excès de mots et des structures de phrases décoratives

  • Transformer les consignes en impératif

    • Dans les consignes, remplacer « You should X » ou « You can X » par le mode impératif du verbe est plus concis
    • « You should save the file to your home directory » devient « Save the file to your home directory »
    • Ce changement réduit le nombre de mots et amène immédiatement le lecteur à l’action

  • Réduire les structures en « of » et « for »

    • Les structures enchaînant « of » ou « for » sont plus efficaces lorsqu’on les réécrit pour placer l’information avant le nom
    • « The manager of the team responsible for marketing » devient « The marketing team’s manager »
    • Une phrase réorganisée permet au lecteur de saisir le sens plus vite, sans devoir réviser sa compréhension à chaque proposition

  • Découper les longues phrases et utiliser les virgules

    • Il vaut mieux diviser les longues phrases en plusieurs phrases courtes
    • L’exemple du projet Acme réunissait dans une seule phrase le jalon, l’environnement serveur, l’amélioration du temps de build et la comparaison avec le plan XYZ ; la version révisée le sépare en trois phrases
    • La version révisée indique séparément que les serveurs non-staging tournent dans l’environnement Foobaz, que le build est passé sous les 10 minutes et qu’avec le plan XYZ il prenait auparavant plus d’une heure
    • Ajouter des virgules aux bons endroits permet au lecteur de traiter la première partie avant de lire la suite
    • « If you’re looking for me, I’ll be in my office »
    • « Due to the fog, our flight was delayed »
    • Lorsqu’une subordonnée apparaît en début de phrase, une virgule est nécessaire ; elle sert de point de traitement qui facilite la lecture

Réduire les formulations qui brouillent l’acteur et le sens

  • Éliminer la voix passive

    • La voix passive masque qui ou quoi accomplit l’action
    • Passer une construction passive à la voix active rend la phrase plus claire, car le lecteur peut relier l’action à la bonne personne ou au bon objet
    • « The fire alarm was pulled and the building was evacuated » révèle les acteurs sous la forme « The fire marshal pulled the alarm and the employees evacuated the building »
    • « Millions of dollars were embezzled from the company » indique qui l’a fait avec « Two executives embezzled millions of dollars from the company »
    • Dans une description système, écrire « An alert is triggered and the job is started » ne dit pas quel service déclenche l’alerte ni quel composant lance la tâche
    • Dans la documentation technique, ne pas préciser le sujet de l’action réduit la précision

  • Utiliser des verbes et descriptions concrets plutôt que des adverbes

    • Les adverbes peuvent presque toujours être remplacés par un verbe ou une description plus précise
    • Dans « He laughed loudly », « loudly » oblige le lecteur à deviner le volume exact ou l’impression produite par le rire
    • Si l’intention réelle est « il a ri si fort que tout le restaurant s’est retourné », mieux vaut décrire directement la situation : c’est plus concret
    • Les adverbes comme « Basically » ou « Essentially » servent souvent de précautions oratoires ; mieux vaut les supprimer et dire directement ce que l’on veut dire

Ne pas présupposer les connaissances ni le ton du lecteur

  • Expliquer les acronymes et les concepts

    • Quand on écrit sur un sujet que l’on connaît bien, il est facile d’oublier le contexte que le lecteur ne possède pas
    • Les acronymes et sigles doivent être développés à leur première occurrence, suivis de l’abréviation entre parenthèses ; ensuite, l’abréviation seule suffit
    • « TTFB » s’écrit d’abord « time to first byte (TTFB) »
    • Ajouter une courte explication lorsqu’un concept apparaît pour la première fois aide le lecteur à suivre
    • Le TTFB mesure le temps écoulé entre l’envoi d’une requête HTTP par l’utilisateur et le chargement du premier octet par le navigateur
    • Il est utilisé comme indicateur de réactivité d’un site web
    • Si nécessaire, vous pouvez fournir un lien pour approfondir, comme time to first byte (TTFB) metric

  • Cohérence du ton

    • Le ton d’un texte, qu’il soit familier ou formel, doit être choisi puis maintenu de manière cohérente
    • Si une phrase commence dans un style très oral puis bascule vers une expression académique, elle peut dérouter le lecteur ou détourner son attention du propos
    • La phrase d’exemple peut être reformulée sur un ton cohérent, du type : « nous étions enthousiastes au départ à propos du nouveau framework, mais nous n’avons pas réussi à obtenir les métriques voulues »

Affiner le jargon, les clichés et la structure visuelle

  • Éviter le jargon et les clichés

    • Le jargon business comprend des expressions comme « deep dive » ou « low-hanging fruit » ; dans d’autres textes, les métaphores tirées du baseball sont aussi des clichés fréquents
    • Le jargon suppose que le lecteur appartient au groupe interne qui utilise ces expressions
    • Pour les lecteurs non anglophones ou peu familiers de la culture du baseball, le jargon et les clichés peuvent rendre le texte difficile à suivre
    • « tl;dr, if you can hack something together by EOD… » contient des abréviations et de l’argot technique, et ne ressemble pas à une demande
    • « Can you deliver a prototype by the end of today? » devient une demande claire qui précise directement le livrable attendu et l’échéance

  • Utiliser les blancs et la mise en forme

    • Les espaces blancs sont importants dans la documentation technique, et ils sont aussi efficaces dans les billets de blog et les e-mails
    • Les longs paragraphes sont difficiles à lire, surtout sur écran, et peuvent faire perdre la concentration du lecteur
    • Découper visuellement la page facilite la recherche des points essentiels
    • Divisez les longs paragraphes en plusieurs paragraphes courts
    • Structurez le texte avec des sous-titres utiles et permettez au lecteur de sauter vers les sections qui l’intéressent
    • Présentez les éléments liés sous forme de listes
    • Lorsqu’il faut transmettre beaucoup d’informations, comme dans une documentation de référence, un tableau peut être préférable à une liste
    • Utilisez le gras pour aider les lecteurs qui parcourent le texte à repérer les points clés

Philosophie de l’édition

  • La philosophie de l’édition peut se résumer en deux points
    • Dire exactement ce que l’on veut dire, sans s’appuyer sur les adverbes, le jargon, les clichés ou les précautions oratoires
    • Supprimer tous les mots inutiles
  • Ces deux principes servent de cadre pour corriger ses propres textes et évaluer ceux des autres
  • Avec la pratique, chacun développe son propre style et ses préférences ; si vous savez pourquoi vous le faites, il est acceptable de s’écarter de certaines recommandations
  • Le but de l’édition n’est pas de suivre des règles sans esprit critique, mais d’être conscient de son usage de la langue et de faire des choix adaptés au message que l’on veut transmettre

À lire aussi

1 commentaires

 
GN⁺ 2024-04-07
Avis Hacker News

  • Je suis l’auteur de cet article. Je suis heureux et honoré qu’il ait parlé à autant de personnes. Après l’avoir écrit, j’ai suivi ma curiosité et je suis devenu moi-même ingénieur logiciel ; après quelques années, les rôles où l’écriture occupe une place importante ont fini par me manquer. Si vous cherchez un excellent rédacteur technique, un developer advocate, ou un rôle mêlant expertise en communication et compétences techniques, faites-le-moi savoir. Vous pouvez me contacter via le formulaire de mon site (https://evaparish.com/contact) ou sur LinkedIn.

    • J’ai vraiment beaucoup retiré de l’article. Je pense qu’il va m’aider à écrire de façon plus concise et claire, et à être mieux compris. Cela dit, après avoir écrit « I really got a lot out of the article. », je me suis demandé si cette phrase était inutile, claire, et si elle exprimait exactement ce que je voulais dire. Au final, c’était bien ce que je voulais dire, et je l’ai développé dans la phrase suivante, mais je serais curieux de savoir ce que vous en pensez.
    • Cela m’a beaucoup rappelé les conseils d’écriture entendus dans la conférence/l’atelier Clear, accurate, concise writing de Jean-luc Doumont.
    • J’ai trouvé assez drôle que l’exemple utilise HTTP sans l’expliquer. Je me demande si c’était une blague intentionnelle.

  • L’une des choses qui m’agacent le plus quand je lis de la documentation technique, c’est de tomber sur des sigles qui n’ont pas encore été présentés au lecteur. Cela se répète à plusieurs endroits dans la documentation de projets, et quand les responsables changent au fil des années, on finit même par ne plus savoir ce que certains sigles signifient. J’ai plusieurs fois vu des situations absurdes où une équipe développe et maintient un service appelé ABC, sans qu’aucun membre de l’équipe ne sache ce que veut dire ABC. Dans ces cas-là, pour éviter d’avoir à choisir un nouveau nom et à mettre à jour toute la documentation associée, on finit par traiter ABC comme un nom propre et passer à autre chose. Faux exemple : pour obtenir un jeton d’accès pour CDIS, allez dans le DMC de , cliquez sur l’élément « CDIS » dans la barre latérale gauche, puis cliquez sur « Generate Access Token » pour copier le jeton. Je préférerais lire quelque chose comme : pour obtenir un jeton d’accès pour Customer Data Indexing Service (CDIS), allez dans la Data Management Console (DMC) de , cliquez sur l’élément « CDIS » dans la barre latérale gauche, puis cliquez sur « Generate Access Token » pour copier le jeton.