Drei Shell-Skripte zum Erkennen von Weasel Words, Passiv und Wortdopplungen

 (matt.might.net)
1 Punkte von GN⁺ 2024-12-15 | 1 Kommentare | Auf WhatsApp teilen
  • Wiederkehrende Schwächen im technischen Schreiben lassen sich besser zuerst durch automatisierte Prüfungen sichtbar machen, statt sie jedes Mal von Menschen anmerken zu lassen. Der Artikel stellt drei Shell-Skripte vor, die sich in den Build von LaTeX-Papers einhängen lassen
  • Ziel ist nicht, Passiv oder bestimmte Formulierungen zu verbieten, sondern anhand der markierten Sätze klarere und präzisere Formulierungen zu wählen
  • Weasel Words wie various, quite, surprisingly, very und extremely verwässern die Präzision; reguläre Ausdrücke helfen, die zu prüfenden Stellen einzugrenzen
  • Die Passivprüfung sucht nach -ed-Formen oder unregelmäßigen Partizipien nach Formen von „be“, während die Prüfung auf doppelte Wörter benachbarte identische Wörter case-insensitive erkennt
  • Bündelt man die drei Prüfungen mit make proof, lassen sie sich im Paper-Repository wiederholt ausführen und verringern, dass sich kleine Fehler zu einem Eindruck von mangelhaftem Korrekturlesen summieren

Wiederkehrende Schwächen im Schreiben durch Automatisierung reduzieren

  • Ein besonders schwieriger Teil bei der Betreuung von Ph.D.-Studierenden ist die Schreibausbildung; wiederkehrende Probleme lassen sich zuerst mit Tools herausfiltern
  • Die Skripte zielen auf drei Probleme ab:
    • übermäßige Verwendung des Passivs
    • Weasel Words
    • lexical illusion, also doppelte Wörter, die man leicht übersieht
  • Diese Skripte werden in das Build-System von LaTeX-Dokumenten integriert
  • Schreibregeln haben Ausnahmen; das Ziel ist daher nicht, bestimmte grammatische Strukturen zu verbieten
  • Wenn ein Satz hervorgehoben wird, soll man selbst prüfen: „Gibt es eine klarere und präzisere Formulierung?“
  • Programmierer können ihre wiederkehrenden Schwächen kennen und Automatisierung nutzen, um sie zu reduzieren

Bücher, die für technisches Schreiben nützlich sind

Stellen, an denen Präzision und Klarheit verloren gehen

  • Olin Shivers lehrte technisches Schreiben als Balance zwischen Präzision, Klarheit und Marketing
  • Im Prozess der Paper-Einreichung zeigen sich Stellen, an denen Präzision und Klarheit auf mechanisch identifizierbare Weise schwächer werden
    • Weasel Words
    • übermäßige Verwendung des Passivs
  • Ein Shell-Skript zu bauen, das auch schlechtes Marketing wissenschaftlicher Ideen erkennt, ist schwierig

Weasel Words erkennen

  • Weasel Words sind Wörter oder Phrasen, die gut klingen, aber kaum Informationen vermitteln und die Präzision eines Satzes verwässern
  • In Texten von Studierenden treten Weasel Words häufig in drei Kategorien auf

  • Salt-and-pepper words

    • Neue Graduate Students streuen manchmal technisch klingende Wörter wie Gewürze in Sätze, ohne tatsächlich Informationen zu vermitteln
    • Typische Ausdrücke sind various, a number of, fairly und quite
    • Entfernt man solche Wörter, wird der Satz stärker
    • 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

    • Beholder words sind Wörter, deren Bedeutung vom Leser abhängt
    • Beispiele sind interestingly, surprisingly, remarkably und clearly
    • Peer Reviewer mögen keine Formulierungen, die ihnen das Urteil abnehmen
    • Statt False positives were surprisingly low. ist es besser, mit To our surprise, false positives were low (3%). Zahlen und die beobachtende Instanz offenzulegen

  • Lazy words und Adverbien

    • Lazy words sind Wörter, die verwendet werden, um keine quantitativen Eigenschaften anzugeben; sie lassen Wissenschaft weniger solide und unfertig wirken
    • Die schlimmsten Beispiele sind very und extremely, die im technischen Schreiben schwer zu rechtfertigen sind
    • Weitere Beispiele sind several, exceedingly, many, most, few und vast
    • Im technischen Schreiben wirken Adverbien tendenziell wie Weasel Words
    • In technischen Texten neuer Graduate Students dürfte das Entfernen aller Adverbien insgesamt einen positiven Nettoeffekt haben
    • We offer a completely different formulation of CFA. ist schlechter als We offer a different formulation of CFA.

  • Skript für Weasel Words

    • Das Bash-Skript definiert eine Standardliste von Weasel Words als regulären Ausdruck und markiert ihre Positionen in Eingabedateien mit egrep -i -n --color
    • Wenn die Standardliste nicht passt, kann eine alternative Listendatei verwendet werden
      • $HOME/etc/words/weasels
      • $WORDSDIR/weasels
      • words/weasels
    • Ohne Argumente gibt es eine Nutzungsmeldung in der Form usage: <script> <file> ... aus

Passiv bewusst einsetzen

  • Im technischen Schreiben ist Passiv nicht immer schlecht
  • Mehr als die Hälfte der von ihm bearbeiteten technischen Texte konnte jedoch allein durch Entfernen von Passiv verbessert werden
    • Studierende übernutzen das Passiv häufiger, als dass sie es gut einsetzen
  • Problematisch ist Passiv, wenn es relevante oder erklärende Informationen verbirgt
    • Termination is guaranteed on any input. verbirgt relevante Informationen
    • Termination is guaranteed on any input by a finite state-space. fügt relevante Informationen hinzu, setzt den Schwerpunkt aber falsch
    • A finite state-space guarantees termination on any input. enthält die relevanten Informationen und ist klarer
  • Wenn das Subjekt wirklich unwichtig ist, kann Passiv besser sein
    • 4 mL HCl were added to the solution.
    • Allerdings wird auch We added 4 mL HCl to the solution. nicht als ernstes Problem gesehen

  • Fragen zur Beurteilung von Passiv

    • Wenn das Skript Passiv markiert, prüft man zwei Dinge
      • Ist der Handelnde relevant, aber unklar?
      • Liest sich der Text besser, wenn man in den Aktiv wechselt?
    • Wenn beide Fragen mit „ja“ beantwortet werden, wechselt man zum Aktiv
    • Wenn nur die erste Frage mit „ja“ beantwortet wird, nennt man den Handelnden explizit

  • Passiv-Skript

    • Das Bash-Skript definiert eine lange Liste unregelmäßiger Partizipien der Vergangenheit
    • Es sucht nach Mustern, bei denen auf am|are|were|being|is|been|was|be ein Leerraum und \w+ed oder ein unregelmäßiges Partizip folgen
    • Mit egrep -n -i --color markiert es die Treffer einschließlich Dateiname und Zeilennummer

Doppelte Wörter und lexical illusion

  • Bei Zeilenumbrüchen übersieht man doppelte Wörter wie the the leicht
  • Ändert man nur den Zeilenumbruch, wird dieselbe Dopplung deutlich sichtbarer
  • Wortdopplungen entstehen beim elektronischen Schreiben und wirken wie Unfälle durch Ausschneiden und Einfügen
  • Besonders häufig passieren sie bei the
  • Ein einzelnes doppeltes Wort führt nicht zur Ablehnung eines Papers, aber kleine Fehler wie Tippfehler und Wortdopplungen summieren sich zu einem Eindruck von mangelhaftem Korrekturlesen
  • Reviewer können fehlendes Korrekturlesen als mangelnden Respekt gegenüber ihrer Zeit und Aufmerksamkeit interpretieren

  • Skript für doppelte Wörter

    • Das Perl-Skript findet benachbarte doppelte Wörter
    • Es liest Dateien zeilenweise und trennt anhand von Nicht-Wort-Zeichen
    • Leerraum wird übersprungen; bei Satzzeichen wird der Zustand des letzten Wortes zurückgesetzt
    • Es vergleicht das aktuelle Wort und das vorherige Wort in Kleinschreibung und gibt bei Gleichheit Dateiname:Zeilennummer Wort aus
    • Der Exit-Code ist die Anzahl der gefundenen Dopplungen

Integration in das Makefile

  • In jedem Paper-Repository liegt eine lokale Kopie der Skripte im Verzeichnis bin/
  • Dem Makefile wird eine Regel make proof hinzugefügt
  • make proof führt die drei Prüfungen nacheinander auf *.tex-Dateien aus
    • sh bin/weasel *.tex
    • sh bin/passive *.tex
    • perl bin/dups *.tex

Paper-Marketing und Peer Review

  • Graduate Students gehen anfangs leicht davon aus, dass es genügt, die ganze Wahrheit zu schreiben, um veröffentlicht zu werden
  • Doch es gibt viele wahre Dinge, und bei führenden Peer-Review-Venues gibt es auch genügend technisch korrekte Papers
  • Peer Review ist eher dazu geworden, zu entscheiden, welche wahren Dinge es wert sind, gewusst zu werden
  • Aus dieser Sicht sind Reviewer die Hüter der knappsten Ressource der wissenschaftlichen Community: der kollektiven Aufmerksamkeit
  • Um ein Paper zu vermarkten, muss man überzeugend zeigen, dass die Idee Zugang zu dieser Ressource verdient

Verwandte Tools und Erweiterungsideen

  • Benjamin Beckwith erstellte, inspiriert von diesen Skripten, den "writegood"-Modus für Emacs
  • John Regehr schlug ein einfaches Skript vor, das unnötige Phrasen wie Note that und Notice that erkennt
  • Andere schlugen Skripte vor, die die Verwendung des Futurs in technischem Schreiben erkennen

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2024-12-15
Meinungen auf Hacker News

  • Materialien, die mir beim Schreiben von Papers geholfen haben, waren How to Write Mathematics von Paul R. Halmos und Mathematical Writing von Donald E. Knuth u. a.
    Um ein Gefühl für klare und präzise Kommunikation zu bekommen, habe ich oft zuerst Halmos gelesen; die „Bad/Better/OK“-Vorschläge erinnern mich an Diskussionen aus den Vorlesungsnotizen von Knuth u. a.
    Als dritter Schritt kann ein Linter wie der vorgeschlagene nützlich sein, um übersehene Stellen zu finden.
    Für alle, die über Themen schreiben, in denen auch nur ein wenig Definitionen vorkommen, halte ich solche Materialien für unverzichtbar.

    • Zusätzlich zu dieser Empfehlung ist auch The Craft of Scientific Writing von M. Alley gut.

  • Wenn dir dieser Beitrag gefällt und du mehr über einen effektiven Prozess zum Schreiben einer Doktorarbeit erfahren möchtest, lohnt sich [1].
    Eigentlich ist es für alle sehenswert, die ihre Kommunikationsfähigkeit verbessern wollen; selbst wenn ich für den Zugriff auf dieses Video bezahlt hätte, hätte ich es nicht bereut.
    [1] https://youtu.be/vtIzMaLkCaM

    • Es wäre schön, ein Repository mit „allem, was man zu Beginn einer Promotion wissen sollte“ zu haben.
      Einschließlich bekannter Materialien wie phd grind.

  • Vielen der Beispiele kann ich schwer zustimmen.
    Wenn man zum Beispiel „It is quite difficult to find untainted samples“ in „It is difficult to find untainted samples“ ändert, liest sich quite difficult deutlich anders als einfach nur difficult.
    Der Satz ist dadurch nicht besser geworden, sondern die Bedeutung hat sich geändert.
    Auch die Tatsache, dass „various methods“ verwendet wurde, enthält die Information, dass es nicht nur eine einzelne Methode war; im zweiten Satz fehlt diese Information.

    • Die Bedeutung, die „quite“ transportiert, kann je nach Leser oder Kontext stark variieren.
      In gesprochener Sprache ändert sie sich je nach Intonation stark, und streng genommen liegt es eher bei „etwas schwierig“, wird aber vielerorts auch im Sinne von „nahezu unmöglich“ verwendet.
      Ich halte es nicht für falsch, das Wort zu entfernen, aber besser wäre es, es durch einen konkreteren Vergleichsausdruck zu ersetzen.
    • Genau so kommt es dazu, dass man am Ende ein 30-seitiges Designdokument liest, obwohl man dasselbe auf 3 Seiten sagen könnte.
      Man sollte versuchen zu verstehen, warum besonders in technischen Dokumenten dekoratives Schreiben so verhasst ist.
      Wenn man viele Papers oder Designs liest, macht einem dieser Stil das Leben schwer.
    • Wenn man sagen will, dass andere Methoden verwendet wurden, sollte man schreiben, was tatsächlich getan wurde.
      Klarer wäre etwa: „We isolated four samples using the following methods…“
    • Die meisten Beispiele sahen für mich miserabel aus.
      Das ist einer der Gründe, warum Papers selbst dann schwer zu lesen sind, wenn sie einfache Inhalte vermitteln.
      Man klammert sich an einen steifen formalen Stil, den niemand mag, und lässt dabei subtile, aber wichtige Kontextsignale weg.

  • Wer nach mehr solchen Tools sucht, sollte sich vale.sh ansehen.
    Man kann verschiedene Arten von Stilrichtlinien hinzufügen, darunter auch das Vermeiden vager Wörter.
    Die GitHub Action, mit der wir Vale bei PRs auf der Website laufen lassen, ist hier: https://github.com/FusionAuth/fusionauth-site/blob/main/.git...
    Die Konfiguration ist hier: https://github.com/FusionAuth/fusionauth-site/tree/main/conf...
    Es hat geholfen, einen Stil durchzusetzen, aber vermutlich nutzen wir die Funktionen nicht voll aus.

    • Vale.sh sieht ziemlich gut aus.
      Ich bearbeite gerade die 3. Auflage eines Buchs und mehrere Website-Artikel, da könnte ich es gut gebrauchen.

  • Ich habe Claude diese Bash-Skripte in eine Web-UI übertragen lassen, damit man Text direkt einfügen und die Ergebnisse sehen kann: https://tools.simonwillison.net/writing-style
    Das Claude-Chatprotokoll ist hier: https://gist.github.com/simonw/e9902ed1cbda30f90db8d0d22caa0...

    • Es scheint nicht richtig zu funktionieren.
      Irgendetwas etwa beim zweiten Pattern-Matching ist seltsam.
      Wenn man zum Beispiel „It is quite difficult to find untainted samples. We used various methods to isolate four samples.“ eingibt, findet es „quite“ in „is quite difficult to find untainted samples.“, aber „various“ in einem leeren String.
      Trotzdem mag ich solche schnellen HTML/JS-Tools.
    • Ich frage mich, warum man Claude anfällige und eingeschränkte Bash-Skripte schreiben lässt, statt einfach Claude selbst den Text prüfen zu lassen.
      Man könnte Claude auch selbst einen Prompt schreiben lassen, der dieselbe Funktion erfüllt oder sie sogar besser erledigt.
      Bash und Perl sind für solche Aufgaben wie Klebeband und Kaugummi, also ziemlich schlechte Werkzeuge, und genau das ist der Bereich, in dem Claude am stärksten ist.
      Statt nur Probleme zu markieren, kann es Alternativen abwägen und Korrekturen vorschlagen, ohne seltsame Regex-Mismatches, die False Positives, False Negatives und Parsing-Fehler erzeugen.

  • Im frühen Unix gab es die Befehle diction und style, die Ähnliches machten.
    Man kann sie von GNU bekommen, und sie sind auch in Homebrew enthalten.
    https://www.gnu.org/software/diction/
    Soweit ich mich erinnere, waren sie nicht besonders großartig, und diese Tool-Sammlung dürfte vermutlich ähnlich gut abschneiden.

  • In meinem Fachgebiet hatte die Qualität des Schreibens die niedrigste Priorität, sogar niedriger als Lehrevaluationen.
    Zwar wird Wert auf klare und prägnante Sätze gelegt, aber als Doktorand ist es vermutlich hilfreicher, vor allem die Fähigkeit zu entwickeln, vor feindseligen Fragen zu präsentieren – und leider auch die Fähigkeit zur Schmeichelei.
    Ja, da steckt bittere Erfahrung dahinter :p

    • Wichtiger als Präsentationsfähigkeiten könnte es sein, sich einen Therapeuten zu suchen.
      Die Leute geraten in kaum zu bewältigender Zahl unter Druck, aber ein erheblicher Teil davon ist selbstgemacht.
      Die tatsächlichen Einsätze sind nicht so hoch, wie man sie im Kopf aufbläht, und die Leute wollen, dass man durchkommt.
    • Ich weiß nicht, wie man das wissen soll.
      Es hängt sicher vom Fach ab, aber nur weil Gutachter die Qualität des Schreibens selten erwähnen, heißt das nicht, dass sie keinen Einfluss auf die Annahme hat.
      Wenn man jemanden nervt, wird er gerade bei Dingen, die ihm nicht wesentlich genug erscheinen, um sie in die Review zu schreiben, eher auch an Stellen kritischer, über die er sonst hinwegsehen würde.
      Ich räume ein, dass das unbefriedigend ist, weil es schwer zu widerlegen ist, und ebenso, dass schlechtes Schreiben in Einzelfällen auch dazu dienen kann, Lücken zu kaschieren.

  • Die Aussage „Um ein Paper zu vermarkten, muss der Autor überzeugend begründen, dass seine Idee den Zugang zu dieser Ressource verdient“ bedeutet letztlich, dass Fachzeitschriften nicht mit den wichtigsten Ideen gefüllt werden, sondern mit den am besten verkauften Papers.
    Wie der Autor sagt, können selbst oberflächliche Faktoren wie schwer zu entdeckende Tippfehler zu Entscheidungsfaktoren werden, weil Gutachter sie finden können.
    Man sollte aufhören, Objektivität vorzutäuschen, und akzeptieren, dass Fachzeitschriften die Vorlieben und Ansichten der Herausgeber widerspiegeln.
    Oder man stellt einfach alles an einen Standardort wie arxiv.
    Beim Hochladen einer PDF gibt es keine knappe Ressource.

    • Die eigentlichen Entscheidungen treffen eher die Gutachter als die Herausgeber.
      Wenn die Gutachter gute oder unauffällige Bewertungen abgeben, wird es einfach veröffentlicht; wenn sie ein Paper verreißen, muss der Herausgeber aufhorchen und beurteilen, ob die Autoren die Einwände der Gutachter ausreichend berücksichtigt haben.
      Trotzdem sind es weiterhin die Gutachter, nicht die Herausgeber, die die Maßstäbe einfordern.
    • Bei der Gelegenheit wäre es schön, auch das Zitationssystem zu verbessern, sodass Literaturangaben zu Hyperlinks werden und man auch auf Code-Artefakte zugreifen kann.

  • Nützlich für Leute, die aus unbekannten Gründen emacs nicht verwenden.
    Der Ablauf, es auszuführen und danach wieder zu editieren, ist umständlich und könnte es schwer machen, daraus einen guten Workflow zu bauen.
    Der Autor schreibt emacs „writegood“ Verdienste zu, aber mein persönliches Lieblings-Plug-in zur Stilkontrolle ist „artbollocks-mode“.

  • Verwandte Beiträge:
    Shell scripts to improve your writing - https://news.ycombinator.com/item?id=13295530 - Januar 2017, 55 Kommentare
    Shell scripts to improve your writing, or "My advisor rewrote himself in bash." - https://news.ycombinator.com/item?id=1529166 - Juli 2010, 31 Kommentare