Três scripts shell para detectar weasel words, voz passiva e palavras duplicadas

 (matt.might.net)
1 pontos por GN⁺ 2024-12-15 | 1 comentários | Compartilhar no WhatsApp
  • Em textos técnicos, fraquezas recorrentes podem ser reveladas primeiro por verificações automatizadas, em vez de alguém apontá-las manualmente toda vez; este artigo apresenta três scripts shell para acoplar ao build de artigos em LaTeX
  • O objetivo não é proibir a voz passiva ou certas expressões, mas fazer com que, ao ver as frases destacadas, você escolha formulações mais claras e precisas
  • Weasel words como various, quite, surprisingly, very e extremely reduzem a precisão, então expressões regulares ajudam a detectá-las e diminuir os pontos a revisar
  • A verificação de voz passiva procura formas em -ed após o verbo be ou particípios irregulares; a verificação de palavras duplicadas encontra palavras idênticas adjacentes, ignorando maiúsculas/minúsculas
  • Ao agrupar as três verificações com make proof, é possível executá-las repetidamente dentro do repositório do artigo e reduzir situações em que pequenos erros acumulados passam a impressão de falta de revisão

Reduzindo fraquezas recorrentes de escrita com automação

  • Uma parte especialmente difícil na orientação de alunos de Ph.D. é o ensino da escrita, e problemas recorrentes podem ser filtrados primeiro por ferramentas
  • Os três problemas que os scripts miram são:
    • uso excessivo da voz passiva
    • weasel words
    • lexical illusion, isto é, palavras duplicadas fáceis de passar despercebidas a olho nu
  • Esses scripts são integrados ao sistema de build de documentos LaTeX
  • Como regras de escrita têm exceções, o objetivo não é proibir uma estrutura gramatical específica
  • Quando uma frase é destacada, isso leva a pessoa a verificar por conta própria: “há uma formulação mais clara e precisa?”
  • Programadores podem reconhecer suas próprias fraquezas recorrentes e usar automação para reduzi-las

Livros úteis como referência para escrita técnica

Pontos por onde precisão e clareza escapam

  • Olin Shivers ensinava escrita técnica como um equilíbrio entre precisão, clareza e marketing
  • Ao passar pelo processo de submissão de artigos, surgem pontos em que precisão e clareza enfraquecem de formas mecanicamente identificáveis
    • weasel words
    • uso excessivo da voz passiva
  • É difícil criar um script shell que também detecte marketing ruim de ideias científicas

Detecção de weasel words

  • Weasel words são palavras ou frases que parecem boas, mas transmitem pouca informação, enfraquecendo a precisão da frase
  • As weasel words frequentes na escrita de alunos se dividem em três tipos

  • Salt and pepper words

    • Novos pós-graduandos às vezes salpicam frases com palavras que parecem técnicas, como tempero, mas que não transmitem informação real
    • Exemplos típicos são various, a number of, fairly e quite
    • Remover essas palavras torna a frase mais 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

    • Beholder words são palavras cujo significado varia conforme o leitor
    • Exemplos incluem interestingly, surprisingly, remarkably e clearly
    • Revisores por pares não gostam de expressões que tentam fazer o julgamento por eles
    • Em vez de False positives were surprisingly low., é melhor explicitar o número e quem observou, como em To our surprise, false positives were low (3%).

  • Lazy words e advérbios

    • Lazy words são palavras usadas para evitar apresentar características quantitativas, fazendo a ciência parecer frágil e inacabada
    • Os piores exemplos são very e extremely, dificilmente aceitáveis em escrita técnica
    • Outros exemplos são several, exceedingly, many, most, few e vast
    • Em escrita técnica, advérbios tendem a parecer weasel words
    • Na escrita técnica de novos pós-graduandos, é provável que eliminar todos os advérbios tenha efeito líquido positivo
    • We offer a completely different formulation of CFA. é pior que We offer a different formulation of CFA.

  • Script de weasel words

    • O script Bash define uma lista básica de weasel words como expressão regular e marca suas posições nos arquivos de entrada com egrep -i -n --color
    • Se a lista padrão não servir, é possível usar um arquivo de lista alternativa
      • $HOME/etc/words/weasels
      • $WORDSDIR/weasels
      • words/weasels
    • Se não houver argumentos, ele imprime uma instrução de uso no formato usage: <script> <file> ...

Lidando conscientemente com a voz passiva

  • Na escrita técnica, a voz passiva nem sempre é ruim
  • Ainda assim, mais da metade dos textos técnicos que editei poderia ter sido melhorada apenas com remoção da voz passiva
    • Alunos costumam abusar da voz passiva mais do que usá-la bem
  • A voz passiva problemática é aquela que oculta informações relevantes ou explicativas
    • Termination is guaranteed on any input. oculta informação relevante
    • Termination is guaranteed on any input by a finite state-space. inclui a informação relevante, mas desloca a ênfase
    • A finite state-space guarantees termination on any input. inclui a informação relevante e é mais clara
  • Quando o sujeito realmente não é importante, a voz passiva pode ser melhor
    • 4 mL HCl were added to the solution.
    • Ainda assim, We added 4 mL HCl to the solution. também não é visto como um problema sério

  • Perguntas para avaliar a voz passiva

    • Quando o script destaca voz passiva, duas coisas devem ser verificadas
      • O agente é relevante, mas está pouco claro?
      • Se mudarmos para voz ativa, o texto fica mais legível?
    • Se a resposta às duas perguntas for “sim”, mude para a voz ativa
    • Se apenas a primeira resposta for “sim”, explicite o agente

  • Script de voz passiva

    • O script Bash define uma longa lista de particípios passados irregulares
    • Ele procura padrões em que am|are|were|being|is|been|was|be é seguido por espaço e \w+ed ou por um particípio irregular
    • Ele exibe os resultados com nome do arquivo e número da linha usando egrep -n -i --color

Palavras duplicadas e lexical illusion

  • Quando há quebra de linha, palavras duplicadas como the the são fáceis de passar despercebidas a olho nu
  • Só mudar a quebra de linha já torna a mesma duplicação mais evidente
  • Duplicação de palavras é um fenômeno do processo de produção de documentos eletrônicos e parece vir de acidentes de recortar e colar
  • Ela ocorre com especial frequência em the
  • Uma única palavra duplicada não leva um artigo à rejeição, mas pequenos erros como erros ortográficos e palavras duplicadas, quando se acumulam, revelam falta de revisão
  • Revisores podem interpretar revisão insuficiente como falta de respeito por seu tempo e atenção

  • Script de palavras duplicadas

    • O script Perl encontra palavras duplicadas adjacentes
    • Ele lê o arquivo linha por linha e separa pelo critério de caracteres que não são de palavra
    • Ignora espaços e, ao encontrar pontuação, reinicializa o estado da última palavra
    • Compara a palavra atual e a palavra anterior em minúsculas; se forem iguais, imprime no formato arquivo:número-da-linha palavra
    • O código de saída é a quantidade de duplicações encontradas

Integração ao Makefile

  • Em cada repositório de artigo, mantém-se uma cópia local dos scripts no diretório bin/
  • Adiciona-se uma regra make proof ao Makefile
  • make proof executa as três verificações em sequência sobre os arquivos *.tex
    • sh bin/weasel *.tex
    • sh bin/passive *.tex
    • perl bin/dups *.tex

Marketing de artigos e revisão por pares

  • No começo, pós-graduandos tendem a achar que basta escrever toda a verdade para serem publicados
  • Mas há muitas coisas verdadeiras, e venues de revisão por pares de alto nível também têm muitos artigos tecnicamente corretos
  • A revisão por pares passou a desempenhar um papel mais próximo de decidir quais coisas verdadeiras vale a pena conhecer
  • Nessa perspectiva, o revisor é guardião do recurso mais limitado da comunidade científica: a atenção coletiva
  • Para fazer o marketing de um artigo, é preciso mostrar de forma convincente que a ideia merece acessar esse recurso

Ferramentas relacionadas e ideias de extensão

  • Benjamin Beckwith se inspirou nesses scripts para criar o modo "writegood" para Emacs
  • John Regehr sugeriu um script simples para detectar frases desnecessárias como Note that e Notice that
  • Outras pessoas sugeriram scripts para detectar o uso do tempo futuro em escrita técnica

Leituras relacionadas

1 comentários

 
GN⁺ 2024-12-15
Comentários do Hacker News

  • Quando eu escrevia artigos acadêmicos, materiais que me ajudaram a melhorar a escrita foram How to Write Mathematics, de Paul R. Halmos, e Mathematical Writing, de Donald E. Knuth e outros
    Para desenvolver um senso de comunicação clara e precisa, eu costumava começar por Halmos, e as sugestões de “Bad/Better/OK” me lembram discussões que vi nas notas de aula de Knuth e outros
    Como terceira etapa, um linter como o proposto pode ser útil para encontrar pontos que passaram batido
    Para quem escreve sobre temas que incluem qualquer grau de definição formal, eu diria que esses materiais são indispensáveis

    • Além dessas recomendações, The Craft of Scientific Writing, de M. Alley, também é muito bom

  • Se você gostou deste texto e quer aprender mais sobre um processo eficaz de escrita de tese de doutorado, vale ver [1]
    Na verdade, qualquer pessoa que queira melhorar sua capacidade de comunicação pode se beneficiar, e eu teria achado o dinheiro bem gasto mesmo se tivesse pago para acessar esse vídeo
    [1] https://youtu.be/vtIzMaLkCaM

    • Seria bom existir um repositório com “tudo o que você precisa saber ao começar o doutorado”
      Incluindo materiais famosos como phd grind

  • É difícil concordar com muitos dos exemplos
    Por exemplo, mudar “It is quite difficult to find untainted samples” para “It is difficult to find untainted samples” faz quite difficult soar bem diferente de apenas difficult
    A frase não melhorou; o significado mudou
    Além disso, o fato de terem usado “various methods” informa que não foi um único método, mas essa informação some na segunda frase

    • O significado transmitido por “quite” pode variar muito dependendo do leitor ou do contexto
      Na fala, isso muda bastante conforme a entonação e, em sentido estrito, é mais próximo de “um pouco difícil”, mas em muitos lugares também é usado como “quase impossível”
      Não acho que remover a palavra esteja necessariamente errado, mas me parece melhor substituí-la por uma expressão comparativa mais específica
    • É por esse tipo de coisa que acabamos lendo um documento de design de 30 páginas que poderia dizer a mesma coisa em 3
      Especialmente em documentação técnica, vale tentar entender por que tanta gente detesta escrita enfeitada
      Ler muitos artigos e documentos de projeto faz esse estilo de prosa virar um tormento
    • Se a intenção é dizer que métodos diferentes foram usados, então escreva de fato o que foi feito
      Algo como “We isolated four samples using the following methods…” é mais claro
    • A maioria dos exemplos parecia bem ruim
      Esse é um dos motivos de artigos acadêmicos serem difíceis de ler mesmo quando estão dizendo algo simples
      Ficam obcecados por uma prosa formal dura, de que ninguém gosta, e acabam removendo pistas de contexto sutis, mas importantes

  • Se você quiser encontrar mais ferramentas desse tipo, vale conferir o vale.sh
    Dá para adicionar vários tipos de guias de estilo, incluindo evitar palavras vagas
    A GitHub Action que usamos para rodar o vale no site no momento do PR está aqui: https://github.com/FusionAuth/fusionauth-site/blob/main/.git...
    A configuração está aqui: https://github.com/FusionAuth/fusionauth-site/tree/main/conf...
    Isso ajudou a impor consistência de estilo, mas provavelmente não estamos aproveitando o máximo das funcionalidades

    • Vale.sh parece bem interessante
      Estou editando agora a 3ª edição de um livro e vários textos para um site, então isso pode ser bem útil

  • Pedi ao Claude para transformar esses scripts em Bash em uma interface web, para que fosse possível colar o código e ver o resultado imediatamente: https://tools.simonwillison.net/writing-style
    O histórico da conversa com o Claude está aqui: https://gist.github.com/simonw/e9902ed1cbda30f90db8d0d22caa0...

    • Não parece estar funcionando direito
      Algo está estranho por volta do segundo pattern matching
      Por exemplo, se você inserir “It is quite difficult to find untainted samples. We used various methods to isolate four samples.”, ele encontra “quite” em “is quite difficult to find untainted samples.” e “various” em uma string vazia
      Ainda assim, gosto desse tipo de ferramenta rápida em HTML/JS
    • Fico me perguntando por que, em vez de mandar o Claude usar scripts em Bash mais frágeis e limitados, não simplesmente pedir ao próprio Claude para revisar o texto
      Você poderia até pedir ao Claude para escrever ele mesmo um prompt que faça a mesma coisa ou melhor
      Bash e Perl são ferramentas improvisadas e frágeis para esse tipo de tarefa, e esse tipo de trabalho é exatamente o que o Claude faz melhor
      Em vez de só marcar problemas, ele pode ponderar alternativas e sugerir revisões, sem incompatibilidades esquisitas de regex que geram falsos positivos, falsos negativos e erros de parsing

  • No Unix inicial, existiam os comandos diction e style, que faziam algo parecido
    Estão disponíveis via GNU e também no Homebrew
    https://www.gnu.org/software/diction/
    Pelo que lembro, eles não eram grande coisa, e este conjunto de ferramentas provavelmente vai ter um desempenho parecido

  • Na minha área, a qualidade da escrita tinha a menor prioridade de todas, até abaixo das avaliações de ensino
    Frases claras e concisas são valorizadas, claro, mas para um pós-graduando talvez seja mais útil desenvolver a capacidade de apresentar diante de perguntas hostis e, tristemente, até a capacidade de bajular
    Sim, falo por amarga experiência :p

    • Pode ser ainda mais importante procurar um terapeuta do que melhorar a capacidade de apresentação
      As pessoas ficam sobrecarregadas a ponto de não dar conta, mas boa parte disso é criada por elas mesmas
      Os interesses reais em jogo não são tão altos quanto você alimentou na cabeça, e as pessoas querem que você passe
    • Não sei como se pode saber disso
      Pode variar conforme a área, mas o fato de os avaliadores não mencionarem muito a qualidade da escrita não significa que isso não afete a aceitação
      Se você irrita alguém, quanto menos essencial parecer ser isso para entrar na resenha, mais fácil é que a pessoa fique crítica até com pontos que normalmente deixaria passar
      Reconheço que isso é difícil de refutar e por isso não é muito satisfatório, e também reconheço que uma escrita seletivamente ruim pode ser usada para esconder buracos

  • A frase “Para fazer marketing de um artigo, o autor precisa apresentar uma justificativa convincente de que sua ideia merece acesso àquele recurso” implica que os periódicos acabam sendo preenchidos não pelas ideias mais importantes, mas pelos artigos mais bem vendidos
    Como o autor diz, até elementos superficiais como erros de digitação difíceis de encontrar podem ser decisivos, porque os avaliadores podem detectá-los
    Precisamos parar de fingir que existe objetividade e aceitar periódicos que refletem os gostos e opiniões dos editores
    Ou então basta colocar tudo em um lugar padrão como o arXiv
    Não existe recurso escasso para fazer upload de um PDF

    • Quem toma a decisão de fato está mais para os avaliadores do que para os editores
      Se os avaliadores dão notas boas ou razoáveis, o artigo é publicado como está; se detonam o artigo, o editor se endireita na cadeira e precisa decidir se os autores refletiram adequadamente as reclamações dos avaliadores
      Ainda assim, quem exige critérios continua sendo os avaliadores, não o editor
    • Aproveitando, seria bom melhorar também o sistema de citações, para que as referências virassem hyperlinks e também fosse possível acessar os artefatos de código

  • Útil para pessoas que, por algum motivo desconhecido, não usam emacs
    O fluxo de rodar e depois voltar a editar é incômodo, então pode ser difícil transformar isso em um bom fluxo de trabalho
    O autor dá crédito ao emacs “writegood”, mas, pessoalmente, meu plugin favorito para policiamento de estilo é o “artbollocks-mode”

  • Postagens relacionadas:
    Shell scripts to improve your writing - https://news.ycombinator.com/item?id=13295530 - janeiro de 2017, 55 comentários
    Shell scripts to improve your writing, or "My advisor rewrote himself in bash." - https://news.ycombinator.com/item?id=1529166 - julho de 2010, 31 comentários