Lo que pienso cuando edito (2019)
(evaparish.com)- Editar, antes de pulir oraciones, consiste en confirmar qué quiere decir realmente el texto y quién es su lector; los mismos principios básicos pueden aplicarse a correos, documentos, blogs y novelas.
- Reiterar el punto central al inicio y al final del texto, y usar sustantivos en lugar de pronombres demostrativos como “this/that”, ayuda a que el lector no pierda el contexto y aumenta la claridad.
- Quitar palabras innecesarias, convertir instrucciones al imperativo y dividir oraciones largas y estructuras con “of/for” hace que el significado se transmita más rápido.
- La voz pasiva, los adverbios, la jerga y los clichés pueden difuminar quién actúa, el significado exacto y el alcance de los lectores; conviene reemplazarlos por verbos y explicaciones concretas.
- Una buena edición no consiste en seguir reglas a ciegas, sino en ser consciente de la elección del lenguaje según el mensaje que se quiere transmitir y eliminar expresiones innecesarias.
Primero decidir qué dice realmente el texto
- Antes de entrar a editar oración por oración, hay que comprobar si el texto realmente dice lo que pretende decir.
- Escribir un preámbulo (preamble) personal para cada texto crea un criterio de edición.
- Las preguntas clave son “¿cuál es el punto principal?” y “¿para quién se escribe?”.
- Anota esta información al inicio del documento y compárala con el contenido real mientras escribes y editas.
- Si no puedes resumir el punto de una entrada de blog en una o dos oraciones, será difícil escribir un texto coherente.
- En las clases de escritura creativa de Writers Studio, en cada tarea se escribe un preámbulo que incluye la voz, el tono y el ambiente previstos; la evaluación se enfoca más en la técnica y en si se logró la intención que en el gusto personal.
La repetición es un mecanismo para mantener al lector
- Aunque el punto central parezca suficientemente claro, repetirlo al inicio y al final del texto ayuda a que el lector siga mejor la idea principal.
- Un tutorial de documentación suele funcionar bien con una estructura que presenta qué se va a hacer, ofrece el procedimiento y luego verifica si se hizo correctamente.
- En una entrada de blog también conviene presentar el tema a tratar, desarrollarlo en el cuerpo y cerrar con un breve resumen.
- La repetición también es necesaria a nivel del lenguaje.
- No uses solo pronombres demostrativos como “this” y “that”; agrega un sustantivo que indique a qué se refieren.
- “To solve this shortage” es más claro que “To solve this”.
- “Successfully authenticating will take you to the home screen” es más claro que “That will take you to the home screen”.
- Aunque al autor le parezca repetición, para el lector funciona como una aclaración que facilita seguir el texto.
Simplificar: quitar palabras que no aportan significado
- La tarea más importante de la edición es eliminar palabras que no contribuyen al significado.
- “You will need to run this script” puede reducirse a “Run this script”.
- “You can aid in readability by making sure…” puede reducirse a “Make sure…”.
- Salvo que haya una razón especial, hay que llegar al punto lo antes posible y no enterrar el significado bajo exceso de palabras o estructuras ornamentales.
-
Convertir las instrucciones al imperativo
- En instrucciones, conviene cambiar “You should X” o “You can X” por el modo imperativo del verbo para que sea más conciso.
- “You should save the file to your home directory” pasa a ser “Save the file to your home directory”.
- Este cambio reduce la cantidad de palabras y lleva al lector directamente a la acción.
-
Reducir estructuras con “of” y “for”
- Las estructuras encadenadas con “of” o “for” son más eficientes si se reescriben colocando la información antes del sustantivo.
- “The manager of the team responsible for marketing” pasa a ser “The marketing team’s manager”.
- La oración reorganizada permite que el lector capte el significado más rápido sin tener que ajustar su interpretación en cada cláusula.
-
Dividir oraciones largas y usar comas
- Conviene dividir las oraciones largas en varias oraciones más cortas.
- El ejemplo del proyecto Acme incluía en una sola oración el milestone, el entorno de servidores, la mejora del tiempo de compilación y la comparación con el XYZ plan; la versión corregida lo separó en tres oraciones.
- La versión corregida comunica por partes que los servidores non-staging se ejecutan en el entorno Foobaz, que la compilación se redujo a menos de 10 minutos y que en el XYZ plan antes tardaba más de una hora.
- Agregar comas en lugares adecuados permite que el lector procese la primera parte antes de leer el resto.
- “If you’re looking for me, I’ll be in my office”
- “Due to the fog, our flight was delayed”
- Cuando una oración empieza con una cláusula subordinada, se necesita una coma; esa coma se convierte en un punto de procesamiento que ayuda a la lectura.
Reducir expresiones que difuminan al actor y el significado
-
Eliminar la voz pasiva
- La voz pasiva oculta quién o qué realiza la acción.
- Cambiar una construcción pasiva a voz activa hace que la oración sea más clara, porque el lector puede vincular la acción con la persona o el objeto correcto.
- “The fire alarm was pulled and the building was evacuated” revela a los actores si se escribe como “The fire marshal pulled the alarm and the employees evacuated the building”.
- “Millions of dollars were embezzled from the company” aclara quién lo hizo si se escribe como “Two executives embezzled millions of dollars from the company”.
- En una explicación de sistemas, escribir “An alert is triggered and the job is started” no muestra qué servicio dispara la alerta ni qué componente ejecuta el trabajo.
- En documentación técnica, no indicar el sujeto de una acción reduce la precisión.
-
Usar verbos y descripciones concretas en lugar de adverbios
- Los adverbios casi siempre pueden reemplazarse por un verbo o una explicación más concreta.
- En “He laughed loudly”, “loudly” obliga al lector a adivinar el volumen o la sensación exacta de la risa.
- Si la intención real es “se rió tan fuerte que todo el restaurante volteó a mirar”, es mejor describir directamente esa situación.
- Adverbios como “Basically” y “Essentially” suelen usarse como mitigadores; conviene quitarlos y decir directamente lo que se quiere decir.
No asumir el conocimiento ni el tono del lector
-
Explicar siglas y conceptos
- Cuando escribes sobre un tema que conoces bien, es fácil olvidar el contexto que el lector quizá no conoce.
- Las siglas y acrónimos deben escribirse completos la primera vez, poniendo la abreviatura entre paréntesis, y luego ya se puede usar solo la abreviatura.
- “TTFB” se escribe primero como “time to first byte (TTFB)”.
- Agregar una breve explicación cuando aparece un concepto por primera vez facilita que el lector pueda seguir.
- TTFB mide el tiempo desde que el usuario envía una solicitud HTTP hasta que el navegador carga el primer byte.
- Se usa como indicador de la capacidad de respuesta de un sitio web.
- Si hace falta, se puede ofrecer un enlace para aprender más, como time to first byte (TTFB) metric.
-
Consistencia del tono
- El tono del texto debe elegirse —coloquial o formal— y mantenerse de forma consistente.
- Si una oración empieza de manera muy coloquial y luego cambia a una expresión académica, puede confundir al lector o desviar su atención de lo que se quiere decir.
- La oración de ejemplo puede reescribirse con un tono consistente, por ejemplo: “al principio nos entusiasmó el nuevo framework, pero no conseguimos las métricas que queríamos”.
Pulir jerga, clichés y estructura visual
-
Evitar jerga y clichés
- En la jerga de negocios hay expresiones como “deep dive” y “low-hanging fruit”; en otros textos suelen aparecer clichés como metáforas de béisbol.
- La jerga asume que el lector pertenece al grupo interno que usa esas expresiones.
- Para lectores que no son hablantes nativos de inglés o que no están familiarizados con la cultura del béisbol, la jerga y los clichés pueden dificultar seguir el texto.
- “tl;dr, if you can hack something together by EOD…” incluye siglas y slang técnico, y no suena como una petición.
- “Can you deliver a prototype by the end of today?” se convierte en una petición clara que pregunta directamente por el entregable necesario y el plazo.
-
Aprovechar el espacio en blanco y el formato
- El espacio en blanco es importante en la documentación técnica y también funciona en entradas de blog y correos.
- Los párrafos largos son difíciles de leer, especialmente en una pantalla de computadora, y pueden hacer que el lector pierda la concentración.
- Dividir visualmente la página facilita encontrar los puntos clave.
- Divide los párrafos largos en varios párrafos cortos.
- Crea estructura con subtítulos útiles y permite que el lector salte a las secciones que le interesan.
- Escribe los elementos relacionados como listas.
- Cuando se entrega mucha información, como en documentos de referencia, una tabla puede ser mejor que una lista.
- Usa negritas para que los lectores que leen por encima puedan captar lo esencial.
Filosofía de edición
- La filosofía de edición puede reducirse a dos cosas:
- Di exactamente lo que quieres decir, sin apoyarte en adverbios, jerga, clichés o mitigadores.
- Elimina todas las palabras innecesarias.
- Estos dos principios se vuelven un marco para corregir tus propios textos y evaluar los de otras personas.
- Con la práctica, desarrollarás tu propio estilo y preferencias; si sabes por qué lo haces, está bien apartarte de algunas recomendaciones.
- El objetivo de editar no es seguir reglas de forma acrítica, sino ser consciente del uso del lenguaje y tomar decisiones acordes con el mensaje que quieres transmitir.
1 comentarios
Opiniones de Hacker News
Soy la persona que escribió este artículo. Me alegra y me honra que haya resonado con tanta gente. Después de escribirlo, seguí mi curiosidad y me convertí en ingeniera de software; tras trabajar varios años, empecé a extrañar un rol con mayor componente de escritura. Si están buscando una excelente redactora técnica, developer advocate, o un rol que combine experiencia en comunicación con capacidades técnicas, avísenme. Pueden contactarme mediante el formulario de mi sitio web (https://evaparish.com/contact) o por LinkedIn.
Una de las cosas que más me molestan al leer documentación técnica es cuando aparecen siglas que todavía no se le presentaron al lector. Esto se repite en varias partes de la documentación de los proyectos y, si con los años cambian las personas responsables, se llega a una situación en la que ya nadie sabe qué significa cierta sigla. De hecho, varias veces vi la situación extraña de que un equipo desarrolla y mantiene un servicio llamado ABC, pero nadie del equipo sabe de qué es sigla ABC. En esos casos se termina tratando ABC como un nombre propio para evitar elegir un nombre nuevo y actualizar toda la documentación relacionada. Ejemplo inventado: Para obtener un token de acceso para CDIS, ve a la DMC de y haz clic en el elemento "CDIS" de la barra lateral izquierda; luego presiona "Generate Access Token" para copiar el token. Preferiría leerlo así: Para obtener un token de acceso para Customer Data Indexing Service (CDIS), ve a la Data Management Console (DMC) de y haz clic en el elemento "CDIS" de la barra lateral izquierda; luego presiona "Generate Access Token" para copiar el token.