Trois scripts shell pour repérer les weasel words, la voix passive et les mots répétés

 (matt.might.net)
1 points par GN⁺ 2024-12-15 | 1 commentaires | Partager sur WhatsApp
  • Dans la rédaction technique, les faiblesses récurrentes peuvent d’abord être mises en évidence par des contrôles automatisés, plutôt que signalées manuellement à chaque fois ; cet article présente trois scripts shell à intégrer à la compilation d’articles LaTeX
  • L’objectif n’est pas d’interdire la voix passive ou certaines expressions, mais d’amener l’auteur à regarder les phrases signalées et à choisir une formulation plus claire et plus précise
  • Les weasel words comme various, quite, surprisingly, very ou extremely brouillent la précision ; les détecter avec des expressions régulières réduit les points à relire
  • Le contrôle de la voix passive cherche les formes en -ed après le verbe be, ainsi que les participes irréguliers ; le contrôle des mots répétés repère les mots identiques adjacents en ignorant la casse
  • En regroupant les trois contrôles avec make proof, on peut les exécuter de façon répétée dans le dépôt d’un article et réduire le risque que de petites erreurs accumulées donnent une impression de relecture insuffisante

Réduire par l’automatisation les faiblesses récurrentes d’écriture

  • Dans l’encadrement de doctorants, l’un des aspects les plus difficiles est l’enseignement de l’écriture ; les problèmes récurrents peuvent d’abord être filtrés par des outils
  • Les scripts ciblent trois problèmes :
    • l’usage excessif de la voix passive
    • les weasel words
    • l’illusion lexicale, c’est-à-dire les mots répétés que l’œil laisse facilement passer
  • Ces scripts s’intègrent au système de compilation des documents LaTeX
  • Les règles d’écriture ont des exceptions ; le but n’est donc pas d’interdire une structure grammaticale donnée
  • Lorsqu’une phrase est mise en évidence, cela pousse à vérifier soi-même s’il existe « une formulation plus claire et plus précise »
  • Un programmeur peut identifier ses propres faiblesses récurrentes et utiliser l’automatisation pour les réduire

Livres utiles pour la rédaction technique

Là où la précision et la clarté s’échappent

  • Olin Shivers enseignait la rédaction technique comme un équilibre entre précision, clarté et marketing
  • Au fil des soumissions d’articles, les points où la précision et la clarté s’affaiblissent de manière mécaniquement identifiable deviennent visibles :
    • les weasel words
    • l’usage excessif de la voix passive
  • Il est difficile de créer un script shell capable de détecter aussi le mauvais marketing d’idées scientifiques

Détection des weasel words

  • Les weasel words sont des mots ou expressions qui semblent bien sonner mais transmettent très peu d’information, et qui brouillent la précision d’une phrase
  • Dans les textes d’étudiants, les weasel words les plus fréquents se répartissent en trois catégories

  • Salt and pepper words

    • Les nouveaux doctorants saupoudrent parfois leurs phrases, comme un assaisonnement, de mots à l’apparence technique, sans transmettre d’information réelle
    • Les expressions typiques sont various, a number of, fairly et quite
    • Supprimer ces mots rend la phrase plus forte
    • It is quite difficult to find untainted samples. → It is difficult to find untainted samples.
    • We used various methods to isolate four samples. → We isolated four samples.

  • Beholder words

    • Les beholder words sont des mots dont le sens varie selon le lecteur
    • Exemples : interestingly, surprisingly, remarkably, clearly
    • Les relecteurs pairs n’aiment pas les formulations qui portent un jugement à leur place
    • Plutôt que False positives were surprisingly low., il vaut mieux expliciter le chiffre et l’observateur, par exemple To our surprise, false positives were low (3%).

  • Lazy words et adverbes

    • Les lazy words sont des mots utilisés pour éviter de donner des caractéristiques quantitatives ; ils donnent à la science une impression de fragilité et d’inachèvement
    • Les pires exemples sont very et extremely, difficilement acceptables dans la rédaction technique
    • Autres exemples : several, exceedingly, many, most, few, vast
    • Dans la rédaction technique, les adverbes ont tendance à ressembler à des weasel words
    • Dans les textes techniques de nouveaux doctorants, supprimer tous les adverbes a de fortes chances d’avoir un effet net positif
    • We offer a completely different formulation of CFA. est moins bon que We offer a different formulation of CFA.

  • Script pour les weasel words

    • Le script Bash définit une liste de weasel words de base sous forme d’expression régulière et indique leur emplacement dans les fichiers d’entrée avec egrep -i -n --color
    • Si la liste par défaut ne convient pas, on peut utiliser un fichier de remplacement :
      • $HOME/etc/words/weasels
      • $WORDSDIR/weasels
      • words/weasels
    • Sans argument, il affiche une aide sous la forme usage: <script> <file> ...

Traiter consciemment la voix passive

  • Dans la rédaction technique, la voix passive n’est pas toujours mauvaise
  • Cependant, plus de la moitié des textes techniques édités auraient pu être améliorés par la seule suppression de la voix passive
    • Les étudiants ont plus souvent tendance à en abuser qu’à bien l’utiliser
  • La voix passive devient problématique lorsqu’elle masque des informations pertinentes ou explicatives
    • Termination is guaranteed on any input. masque une information pertinente
    • Termination is guaranteed on any input by a finite state-space. ajoute l’information pertinente, mais l’accent n’est pas mis au bon endroit
    • A finite state-space guarantees termination on any input. contient l’information pertinente et est plus nette
  • Quand le sujet n’a vraiment pas d’importance, la voix passive peut être préférable
    • 4 mL HCl were added to the solution.
    • Cela dit, We added 4 mL HCl to the solution. ne serait pas non plus considéré comme un problème grave

  • Questions pour juger la voix passive

    • Lorsque le script signale une voix passive, il faut vérifier deux points :
      • l’agent est-il pertinent mais peu clair ?
      • le texte se lit-il mieux si l’on passe à la voix active ?
    • Si la réponse aux deux questions est « oui », on passe à la voix active
    • Si seule la première réponse est « oui », on explicite l’agent

  • Script pour la voix passive

    • Le script Bash définit une longue liste de participes passés irréguliers
    • Il recherche un motif dans lequel am|are|were|being|is|been|was|be est suivi d’un espace puis de \w+ed ou d’un participe irrégulier
    • Il affiche les correspondances avec nom de fichier et numéro de ligne via egrep -n -i --color

Mots répétés et illusion lexicale

  • En présence d’un retour à la ligne, un mot répété comme the the peut facilement échapper à l’œil
  • Le même doublon devient plus évident si l’on modifie simplement les retours à la ligne
  • La répétition de mots est un phénomène lié à la rédaction de documents électroniques et ressemble à un accident de couper-coller
  • Elle se produit particulièrement souvent avec the
  • Un seul mot répété ne fera pas rejeter un article, mais l’accumulation de petites erreurs comme des fautes d’orthographe et des mots répétés révèle une relecture insuffisante
  • Un relecteur peut interpréter un manque de relecture comme un manque de respect pour son temps et son attention

  • Script pour les mots répétés

    • Le script Perl cherche les mots identiques adjacents
    • Il lit le fichier ligne par ligne et le découpe sur les caractères non alphabétiques
    • Il ignore les espaces et réinitialise l’état du dernier mot lorsqu’il rencontre un signe de ponctuation
    • Il compare le mot courant et le mot précédent en minuscules et, s’ils sont identiques, affiche le résultat au format nom_de_fichier:numéro_de_ligne mot
    • Le code de sortie correspond au nombre de doublons trouvés

Intégration au Makefile

  • Une copie locale des scripts est placée dans le répertoire bin/ de chaque dépôt d’article
  • Une règle make proof est ajoutée au Makefile
  • make proof exécute successivement les trois contrôles sur les fichiers *.tex :
    • sh bin/weasel *.tex
    • sh bin/passive *.tex
    • perl bin/dups *.tex

Marketing d’article et revue par les pairs

  • Les doctorants ont souvent tendance, au début, à penser qu’il suffit d’écrire toute la vérité pour être publié
  • Mais il existe beaucoup de choses vraies, et les grandes venues de revue par les pairs reçoivent déjà largement assez d’articles techniquement corrects
  • La revue par les pairs ressemble de plus en plus à un mécanisme qui détermine quelles vérités méritent d’être connues
  • Dans cette perspective, les relecteurs sont les gardiens de la ressource la plus limitée de la communauté scientifique : l’attention collective
  • Pour « marketer » un article, il faut montrer de façon convaincante que l’idée mérite d’accéder à cette ressource

Outils liés et idées d’extension

  • Benjamin Beckwith s’est inspiré de ces scripts pour créer le mode "writegood" pour Emacs
  • John Regehr a proposé un script simple pour repérer les tournures inutiles comme Note that ou Notice that
  • D’autres personnes ont suggéré des scripts pour détecter l’usage du futur dans la rédaction technique

À lire aussi

1 commentaires

 
GN⁺ 2024-12-15
Avis Hacker News

  • À l’époque où j’écrivais des articles scientifiques, les ressources qui m’ont aidé à améliorer mon écriture étaient How to Write Mathematics de Paul R. Halmos et Mathematical Writing de Donald E. Knuth et al.
    Pour acquérir le sens d’une communication claire et précise, je commençais souvent par Halmos, et les suggestions « Bad/Better/OK » me rappellent les discussions vues dans les notes de cours de Knuth et al.
    Comme troisième étape, un linter comme celui proposé peut être utile pour repérer ce qui manque.
    Pour quiconque écrit sur un sujet qui comporte ne serait-ce qu’un peu de définition, je considère ces ressources comme indispensables.

    • En plus de cette recommandation, The Craft of Scientific Writing de M. Alley est aussi très bon.

  • Si cet article vous plaît et que vous voulez en savoir plus sur une méthode efficace de rédaction de thèse de doctorat, regardez [1].
    En réalité, il vaut le détour pour toute personne souhaitant améliorer ses compétences de communication, et je n’aurais pas regretté d’avoir payé pour accéder à cette vidéo.
    [1] https://youtu.be/vtIzMaLkCaM

    • Ce serait bien d’avoir un dépôt qui rassemble « tout ce qu’il faut savoir quand on commence un doctorat ».
      En incluant aussi des ressources connues comme phd grind.

  • J’ai du mal à être d’accord avec beaucoup des exemples.
    Par exemple, si l’on remplace « It is quite difficult to find untainted samples » par « It is difficult to find untainted samples », quite difficult et un simple difficult se lisent assez différemment.
    La phrase n’a pas été améliorée, son sens a changé.
    De même, le fait d’avoir écrit « various methods » apporte l’information qu’il ne s’agissait pas d’une seule méthode, information qui disparaît dans la deuxième phrase.

    • Le sens transmis par « quite » peut varier fortement selon le lecteur ou le contexte.
      À l’oral, il change beaucoup selon l’intonation ; strictement parlant, il est plus proche de « légèrement difficile », mais dans beaucoup d’endroits il est aussi utilisé comme « presque impossible ».
      Je ne pense pas que supprimer le mot soit forcément erroné, mais je trouve préférable de le remplacer par une comparaison plus précise.
    • C’est ce genre de choses qui fait qu’on finit par lire un document de conception de 30 pages alors que 3 pages suffiraient à dire la même chose.
      Il serait utile d’essayer de comprendre pourquoi, surtout dans la documentation technique, l’écriture décorative est autant détestée.
      Quand on lit beaucoup d’articles ou de conceptions, ce style rend la vie pénible.
    • Si l’on veut dire que différentes méthodes ont été utilisées, il suffit d’écrire ce qui a réellement été fait.
      Une formulation comme « We isolated four samples using the following methods… » est plus claire.
    • La plupart des exemples me paraissaient franchement mauvais.
      C’est précisément l’une des raisons pour lesquelles les articles scientifiques sont difficiles à lire, même lorsqu’ils disent des choses simples.
      Ils s’accrochent à un style formel rigide que personne n’apprécie, tout en supprimant des indices de contexte subtils mais importants.

  • Si vous cherchez d’autres outils de ce genre, vale.sh vaut le coup d’œil.
    On peut y ajouter plusieurs types de consignes de style, y compris pour éviter les mots ambigus.
    La GitHub Action que nous utilisons pour lancer vale sur le site web au moment des PR est ici : https://github.com/FusionAuth/fusionauth-site/blob/main/.git...
    La configuration est ici : https://github.com/FusionAuth/fusionauth-site/tree/main/conf...
    Cela nous a aidés à faire respecter un style, même si nous n’en exploitons probablement pas toutes les fonctionnalités.

    • Vale.sh a l’air plutôt bien.
      Je suis en train de relire la troisième édition d’un livre et plusieurs articles pour un site web, cela pourrait donc m’être utile.

  • J’ai demandé à Claude de porter ces scripts Bash dans une interface web, afin de pouvoir coller directement du texte et voir le résultat : https://tools.simonwillison.net/writing-style
    L’historique de la conversation avec Claude est ici : https://gist.github.com/simonw/e9902ed1cbda30f90db8d0d22caa0...

    • Cela ne semble pas fonctionner correctement.
      Il y a quelque chose d’étrange vers la deuxième correspondance de motif.
      Par exemple, si l’on saisit « It is quite difficult to find untainted samples. We used various methods to isolate four samples. », il trouve « quite » dans « is quite difficult to find untainted samples. », et « various » dans une chaîne vide.
      Cela dit, j’aime bien ce genre de petits outils HTML/JS rapides.
    • Je me demande pourquoi ne pas simplement demander à Claude lui-même de relire le texte, plutôt que de lui faire écrire des scripts Bash plus fragiles et limités.
      On pourrait même demander à Claude de rédiger lui-même un prompt qui fait la même chose, voire mieux.
      Bash et Perl sont de mauvais outils pour ce travail, comme du ruban adhésif et du chewing-gum, alors que c’est précisément le domaine où Claude excelle.
      Au lieu de simplement signaler des problèmes, il peut peser les alternatives et proposer des corrections, sans faux positifs, faux négatifs ni incohérences bizarres de regex qui provoquent des erreurs de parsing.

  • Les premiers Unix avaient des commandes diction et style qui faisaient un travail similaire.
    Elles sont disponibles chez GNU et figurent aussi dans Homebrew.
    https://www.gnu.org/software/diction/
    De mémoire, ce n’était pas extraordinaire, et cette série d’outils fera probablement à peu près aussi bien.

  • Dans mon domaine, la qualité de l’écriture était tout en bas de l’échelle des priorités, encore plus bas que les évaluations de cours.
    On accorde bien de l’importance à des phrases claires et concises, mais pour un doctorant, il me semble plus utile de développer surtout sa capacité à présenter face à des questions hostiles, et, tristement, sa capacité à flatter.
    Oui, c’est du vécu douloureux :p

    • Trouver un thérapeute peut être encore plus important que les compétences de présentation.
      Les gens se mettent une pression impossible à gérer, mais une bonne partie de cette pression est auto-infligée.
      Les véritables enjeux ne sont pas aussi élevés que ceux qu’on a amplifiés dans sa tête, et les gens veulent que vous réussissiez.
    • Je ne vois pas comment on peut le savoir.
      Cela dépend sans doute du domaine, mais le fait que les évaluateurs ne mentionnent pas beaucoup la qualité de l’écriture ne veut pas dire qu’elle n’influe pas sur l’acceptation.
      Si vous agacez quelqu’un, surtout d’une manière qui ne lui semble pas assez substantielle pour être écrite dans une évaluation, il aura d’autant plus tendance à devenir plus critique sur des points qu’il aurait normalement laissés passer.
      Je reconnais que c’est insatisfaisant parce que difficile à réfuter, et je reconnais aussi qu’une mauvaise écriture peut parfois être utilisée délibérément pour masquer des failles.

  • Dire que « pour vendre un article, l’auteur doit présenter un argument convaincant montrant que son idée mérite d’accéder à cette ressource » revient à dire que les revues scientifiques sont remplies non pas des idées les plus importantes, mais des articles les mieux vendus.
    Comme le dit l’auteur, même des éléments superficiels comme des coquilles difficiles à repérer peuvent être relevés par les évaluateurs, et deviennent donc souvent des facteurs décisifs.
    Il faut arrêter de faire semblant d’être objectif, et accepter que les revues reflètent les goûts et les opinions de leurs éditeurs.
    Ou alors on peut tout mettre dans un lieu standard comme arxiv.
    Il n’y a pas de ressource rare dans le fait d’uploader un PDF.

    • En pratique, ceux qui prennent les décisions sont plutôt les évaluateurs que les éditeurs.
      Si les évaluateurs donnent une bonne note ou une note acceptable, l’article est publié tel quel ; s’ils le descendent en flammes, l’éditeur se redresse sur sa chaise et doit juger si les auteurs ont suffisamment répondu aux griefs des évaluateurs.
      Mais ceux qui imposent les critères restent les évaluateurs, pas les éditeurs.
    • Tant qu’à faire, ce serait bien d’améliorer aussi le système de citation, pour que les références deviennent des hyperliens et que l’on puisse accéder aux artefacts de code.

  • Utile pour les personnes qui, pour des raisons inconnues, n’utilisent pas emacs.
    Le flux consistant à lancer l’outil puis à rééditer ensuite est laborieux, et pourrait être difficile à transformer en bon workflow.
    L’auteur crédite emacs « writegood », mais mon plugin préféré de police du style reste personnellement « artbollocks-mode ».

  • Articles liés :
    Shell scripts to improve your writing - https://news.ycombinator.com/item?id=13295530 - janvier 2017, 55 commentaires
    Shell scripts to improve your writing, or "My advisor rewrote himself in bash." - https://news.ycombinator.com/item?id=1529166 - juillet 2010, 31 commentaires