3 scripts de shell para detectar weasel words, voz pasiva y palabras duplicadas

 (matt.might.net)
1 puntos por GN⁺ 2024-12-15 | 1 comentarios | Compartir por WhatsApp
  • En la escritura técnica, las debilidades que se repiten pueden hacerse visibles primero con verificaciones automatizadas en lugar de depender de que una persona las señale cada vez; este artículo presenta 3 scripts de shell para integrarlos al build de artículos en LaTeX
  • El objetivo no es prohibir la voz pasiva ni ciertas expresiones, sino hacer que, al ver las oraciones marcadas, uno elija expresiones más claras y precisas
  • Weasel words como various, quite, surprisingly, very y extremely diluyen la precisión, así que se detectan con expresiones regulares para reducir los puntos que revisar
  • La verificación de voz pasiva busca formas en -ed o participios irregulares después de un verbo to be, y la de palabras duplicadas detecta palabras iguales adyacentes ignorando mayúsculas y minúsculas
  • Si se agrupan las tres verificaciones con make proof, pueden ejecutarse repetidamente dentro del repositorio del artículo y reducir casos en los que pequeños errores acumulados hagan que el texto parezca insuficientemente corregido

Reducir debilidades recurrentes de escritura con automatización

  • Una parte especialmente difícil al orientar a estudiantes de Ph.D. es la enseñanza de escritura, y los problemas que aparecen una y otra vez pueden filtrarse primero con herramientas
  • Los tres problemas a los que apuntan estos scripts son los siguientes
    • abuso de la voz pasiva
    • weasel words
    • lexical illusion, es decir, palabras duplicadas que son fáciles de pasar por alto a simple vista
  • Estos scripts se usan integrados en el sistema de build de documentos LaTeX
  • Las reglas de escritura tienen excepciones, así que el objetivo no es prohibir una estructura gramatical concreta
  • Cuando una oración queda resaltada, uno mismo puede comprobar si “hay una forma más clara y precisa de decir esto”
  • Si eres programador, puedes conocer tus debilidades recurrentes y usar la automatización para reducirlas

Libros útiles como referencia para escritura técnica

Dónde se escapan la precisión y la claridad

  • Olin Shivers enseñaba la escritura técnica como un equilibrio entre precisión, claridad y marketing
  • Al pasar por el proceso de envío de artículos, se hicieron visibles puntos donde la precisión y la claridad se debilitan de maneras identificables mecánicamente
    • weasel words
    • abuso de la voz pasiva
  • Es difícil hacer un script de shell que detecte incluso el mal marketing de las ideas científicas

Detección de weasel words

  • Las weasel words son palabras o frases que suenan bien pero transmiten muy poca información, y debilitan la precisión de una oración
  • En la escritura de estudiantes aparecen con frecuencia tres tipos de weasel words

  • Salt and pepper words

    • Los nuevos estudiantes de posgrado a veces espolvorean sus oraciones con palabras que suenan técnicas, como si fueran condimento, pero en realidad no comunican información
    • Expresiones representativas son various, a number of, fairly y quite
    • Quitar estas palabras fortalece la oración
    • 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

    • Las beholder words son palabras cuyo significado cambia según el lector
    • Algunos ejemplos son interestingly, surprisingly, remarkably, clearly
    • A los revisores por pares no les gusta que una expresión decida el juicio por ellos
    • En vez de False positives were surprisingly low., es mejor algo como To our surprise, false positives were low (3%)., donde se muestran la cifra y el sujeto de la observación

  • Lazy words y adverbios

    • Las lazy words son palabras usadas para evitar presentar propiedades cuantitativas, y hacen que la ciencia se vea menos sólida y más incompleta
    • Los peores ejemplos son very y extremely, difíciles de aceptar en escritura técnica
    • Otros ejemplos son several, exceedingly, many, most, few, vast
    • En escritura técnica, los adverbios tienden a parecer weasel words
    • En la escritura técnica de estudiantes nuevos de posgrado, es muy probable que eliminar todos los adverbios tenga un efecto neto positivo
    • We offer a completely different formulation of CFA. es peor que We offer a different formulation of CFA.

  • Script de weasel words

    • El script en Bash define una lista base de weasel words como expresión regular y marca sus posiciones en el archivo de entrada con egrep -i -n --color
    • Si la lista base no encaja, puede usarse un archivo alternativo con la lista
      • $HOME/etc/words/weasels
      • $WORDSDIR/weasels
      • words/weasels
    • Si no hay argumentos, imprime el uso con el formato usage: <script> <file> ...

Tratar la voz pasiva de forma consciente

  • La voz pasiva no siempre es mala en la escritura técnica
  • Aun así, más de la mitad de los textos técnicos editados podrían mejorar solo con eliminar la voz pasiva
    • Los estudiantes tienden más a abusar de la voz pasiva que a usarla bien
  • La voz pasiva problemática es la que oculta información relevante o explicativa
    • Termination is guaranteed on any input. oculta información relevante
    • Termination is guaranteed on any input by a finite state-space. incluye la información relevante, pero pone el énfasis en el lugar equivocado
    • A finite state-space guarantees termination on any input. incluye la información relevante y es más nítida
  • Cuando el sujeto realmente no importa, la voz pasiva puede ser mejor
    • 4 mL HCl were added to the solution.
    • Aun así, We added 4 mL HCl to the solution. tampoco parece un problema serio

  • Preguntas para evaluar la voz pasiva

    • Cuando el script marca una construcción pasiva, conviene revisar dos cosas
      • si el agente es relevante pero no está claro
      • si al pasarla a voz activa el texto se lee mejor
    • Si ambas respuestas son “sí”, se cambia a voz activa
    • Si solo la primera es “sí”, se explicita el agente

  • Script de voz pasiva

    • El script en Bash define una lista larga de participios pasados irregulares
    • Busca un patrón con am|are|were|being|is|been|was|be seguido de un espacio y \w+ed o un participio irregular
    • Lo muestra con egrep -n -i --color, incluyendo nombre de archivo y número de línea

Palabras duplicadas y lexical illusion

  • Si hay saltos de línea, es fácil que a simple vista se escape una palabra duplicada como the the
  • Con solo cambiar los saltos de línea, la misma duplicación puede verse mucho más clara
  • La duplicación de palabras es un fenómeno que aparece durante la redacción electrónica de documentos y parece surgir de accidentes de cortar y pegar
  • Ocurre especialmente con the
  • Un solo caso de palabra duplicada no hará que rechacen un artículo, pero si se acumulan errores pequeños como faltas ortográficas y duplicaciones, queda en evidencia una corrección insuficiente
  • Un revisor puede interpretar esa falta de corrección como una falta de respeto por su tiempo y su atención

  • Script de palabras duplicadas

    • El script en Perl detecta palabras duplicadas adyacentes
    • Lee el archivo línea por línea y separa usando caracteres no alfanuméricos como delimitadores
    • Omite espacios en blanco y, al encontrar puntuación, reinicia el estado de la última palabra
    • Compara en minúsculas la palabra actual con la anterior y, si son iguales, imprime con el formato archivo:número_de_línea palabra
    • El código de salida es la cantidad de duplicados encontrados

Integración en el Makefile

  • Se deja una copia local de los scripts en el directorio bin/ de cada repositorio de artículos
  • Se agrega una regla make proof al Makefile
  • make proof ejecuta las tres verificaciones en secuencia sobre los archivos *.tex
    • sh bin/weasel *.tex
    • sh bin/passive *.tex
    • perl bin/dups *.tex

Marketing de artículos y revisión por pares

  • Al principio, a los estudiantes de posgrado les resulta fácil pensar que con escribir toda la verdad bastará para publicar
  • Pero hay muchas cosas verdaderas, y en los venues de revisión por pares de primer nivel también sobran artículos técnicamente correctos
  • La revisión por pares se ha acercado más a decidir qué cosas verdaderas vale la pena conocer
  • Desde esta perspectiva, los revisores son guardianes del recurso más limitado de la comunidad científica: la atención colectiva
  • Para hacer marketing de un artículo, hay que mostrar de forma convincente que la idea merece acceso a ese recurso

Herramientas relacionadas e ideas de extensión

  • Benjamin Beckwith se inspiró en estos scripts para crear el modo de Emacs "writegood"
  • John Regehr propuso un script simple para detectar frases innecesarias como Note that y Notice that
  • Otras personas propusieron scripts para detectar el uso de futuro en escritura técnica

Lecturas relacionadas

1 comentarios

 
GN⁺ 2024-12-15
Opiniones en Hacker News

  • Cuando escribía artículos académicos, los materiales que me ayudaron a mejorar mi escritura fueron How to Write Mathematics, de Paul R. Halmos, y Mathematical Writing, de Donald E. Knuth y otros.
    Para desarrollar un sentido de comunicación clara y precisa, solía empezar leyendo a Halmos, y las sugerencias “Bad/Better/OK” me recuerdan las discusiones que vi en las notas de clase de Knuth y otros.
    Como tercer paso, un linter como el propuesto podría ser útil para detectar lo que se escapa.
    Para cualquiera que escriba sobre temas que incluyan aunque sea un poco de definición, creo que estos materiales son imprescindibles.

    • Además de esa recomendación, The Craft of Scientific Writing, de M. Alley, también es bueno.

  • Si te gustó este artículo y quieres conocer más sobre un proceso eficaz de redacción de tesis doctoral, conviene ver [1].
    En realidad, vale la pena para cualquiera que quiera mejorar sus habilidades de comunicación, y hasta habría sentido que valía la pena pagar por acceder a este video.
    [1] https://youtu.be/vtIzMaLkCaM

    • Sería bueno que existiera un repositorio con “todo lo que deberías saber al empezar un doctorado”.
      Incluyendo materiales famosos como phd grind.

  • Me cuesta estar de acuerdo con muchos de los ejemplos.
    Por ejemplo, si se cambia “It is quite difficult to find untainted samples” por “It is difficult to find untainted samples”, quite difficult y simplemente difficult se leen de forma bastante distinta.
    La oración no mejoró; cambió el significado.
    Además, el hecho de haber escrito “various methods” transmite la información de que no fue un solo método, pero en la segunda oración esa información desaparece.

    • El significado que transmite “quite” puede variar mucho según el lector o el contexto.
      Al hablar, cambia bastante según la entonación, y en sentido estricto se acerca más a “algo difícil”, pero en muchos lugares también se usa como “casi imposible”.
      No creo que eliminar la palabra esté mal, pero me parece mejor reemplazarla por una expresión comparativa más específica.
    • Por cosas como esta uno termina leyendo un documento de diseño de 30 páginas que podría decir lo mismo en 3 páginas.
      Sería bueno intentar entender por qué, especialmente en la documentación técnica, a algunos les molesta tanto la escritura decorativa.
      Si lees muchos papers o diseños, ese estilo te hace la vida miserable.
    • Si quieres decir que usaste otros métodos, basta con escribir qué hiciste realmente.
      Es más claro escribir algo como “We isolated four samples using the following methods…”.
    • La mayoría de los ejemplos me parecieron pésimos.
      Esta es precisamente una de las razones por las que los papers son difíciles de leer incluso cuando dicen cosas simples.
      Se aferran a un estilo formal rígido que no le gusta a nadie y, al mismo tiempo, eliminan pistas de contexto sutiles pero importantes.

  • Si buscas más herramientas de este tipo, vale la pena revisar vale.sh.
    Permite agregar varios tipos de guías de estilo, incluida la evitación de palabras ambiguas.
    La GitHub Action que uso para ejecutar vale en el sitio web al momento de un PR está aquí: https://github.com/FusionAuth/fusionauth-site/blob/main/.git...
    La configuración está aquí: https://github.com/FusionAuth/fusionauth-site/tree/main/conf...
    Me ayudó a imponer el estilo, aunque probablemente no estoy aprovechando al máximo sus funciones.

    • Vale.sh se ve bastante bien.
      Ahora estoy editando la tercera edición de un libro y varios artículos del sitio web, así que podría serme útil.

  • Le pedí a Claude que llevara esos scripts Bash a una UI web, para poder pegar el código directamente y ver los resultados: https://tools.simonwillison.net/writing-style
    El historial de la conversación con Claude está aquí: https://gist.github.com/simonw/e9902ed1cbda30f90db8d0d22caa0...

    • Parece que no funciona correctamente.
      Algo anda raro alrededor de la segunda coincidencia de patrones.
      Por ejemplo, si ingresas “It is quite difficult to find untainted samples. We used various methods to isolate four samples.”, encuentra “quite” en “is quite difficult to find untainted samples.” y “various” en una cadena vacía.
      Aun así, me gustan este tipo de herramientas rápidas en HTML/JS.
    • Me pregunto por qué no hacer que Claude revise el texto directamente, en vez de pedirle que use scripts Bash más frágiles y limitados.
      Incluso podrías pedirle a Claude que escriba por sí mismo un prompt que haga la misma función, o que la haga mejor.
      Bash y Perl son herramientas tipo cinta adhesiva y chicle para esta tarea, bastante malas, y esto es precisamente de lo que Claude mejor sabe hacer.
      En lugar de simplemente marcar problemas, puede sopesar alternativas y sugerir correcciones, sin falsos positivos, falsos negativos ni errores de parsing causados por discrepancias raras en regex.

  • En los primeros tiempos de Unix existían comandos llamados diction y style que hacían algo parecido.
    Se pueden obtener en GNU y también están en Homebrew.
    https://www.gnu.org/software/diction/
    Según recuerdo, no eran gran cosa, y este conjunto de herramientas probablemente lo haga más o menos igual de bien.

  • En mi campo, la calidad de la escritura estaba en el nivel más bajo de importancia, incluso por debajo de las evaluaciones de los cursos.
    Aunque se valoran las frases claras y concisas, si eres estudiante de posgrado, creo que te ayudaría más desarrollar la capacidad de presentar, especialmente ante preguntas hostiles, y, tristemente, la capacidad de adular.
    Sí, tuve una experiencia amarga :p

    • Puede ser más importante buscar un terapeuta que mejorar tus habilidades de presentación.
      La gente se abruma hasta un punto que no puede manejar, pero buena parte de eso se lo genera a sí misma.
      Los intereses reales en juego no son tan altos como los que te has imaginado, y la gente quiere que apruebes.
    • No sé cómo podrías saber eso.
      Dependerá del campo, pero que los evaluadores no mencionen mucho la calidad de la escritura no significa que no influya en la aceptación.
      Si irritas a alguien, cuanto más sienta que es algo no tan esencial como para escribirlo en una revisión, más fácil es que se vuelva más crítico incluso con aspectos que normalmente habría dejado pasar.
      Admito que esto no es satisfactorio porque es difícil de refutar, y también admito que, selectivamente, una mala escritura puede usarse para tapar huecos.

  • Decir que “para promocionar un paper, el autor debe presentar un argumento convincente de que su idea merece acceder a ese recurso” significa que las revistas académicas se llenan no con las ideas más importantes, sino con los papers que mejor se vendieron.
    Como dice el autor, incluso elementos superficiales como erratas difíciles de detectar pueden convertirse en factores decisivos porque los evaluadores pueden encontrarlos.
    Hay que dejar de fingir objetividad y aceptar revistas que reflejen los gustos y opiniones de los editores.
    O bien, subir todo a un lugar estándar como arxiv.
    No hay recursos escasos para subir un PDF.

    • Quienes toman las decisiones reales son más bien los evaluadores, no los editores.
      Si los evaluadores dan una buena calificación o una calificación aceptable, se publica tal cual; si destrozan el paper, el editor se incorpora en la silla y tiene que decidir si los autores atendieron suficientemente las quejas de los evaluadores.
      Aun así, quienes siguen exigiendo los criterios son los evaluadores, no los editores.
    • Ya que estamos, sería bueno mejorar también el sistema de citas para que las referencias sean hipervínculos y se pueda acceder a los artefactos de código.

  • Útil para quienes, por razones desconocidas, no usan emacs.
    El flujo de ejecutar esto y luego volver a editar puede ser engorroso, así que quizá sea difícil convertirlo en un buen flujo de trabajo.
    El autor le da crédito a “writegood” de emacs, pero mi plugin favorito para vigilar el estilo es “artbollocks-mode”.

  • Artículos relacionados:
    Shell scripts to improve your writing - https://news.ycombinator.com/item?id=13295530 - enero de 2017, 55 comentarios
    Shell scripts to improve your writing, or "My advisor rewrote himself in bash." - https://news.ycombinator.com/item?id=1529166 - julio de 2010, 31 comentarios