Las cosas en las que pienso al editar (2019)

Las cosas en las que pienso al editar un texto

• Haz que el texto comunique con precisión

  • Antes de escribir, hay que decidir qué se quiere decir.
  • Se debe definir claramente el propósito del texto teniendo en cuenta el tema, el público objetivo, etc., y anotarlo al inicio del documento.
  • Durante el proceso de escritura y edición, se mantiene la coherencia comparándolo con ese propósito.

• Repite dentro de límites razonables

  • Para que el lector pueda entender el tema, se vuelve a confirmar al inicio y al final del texto.
  • Para mayor claridad, puede ayudar repetir usando sustantivos en lugar de verbos.

• Simplifica

  • Elimina las palabras innecesarias y haz las oraciones más concisas.
  • Sustituye expresiones como "usted" o "usted puede" por instrucciones breves y directas.
  • Divide las oraciones largas en otras más cortas y usa las comas adecuadamente para ayudar a la comprensión del lector.

• Elimina la voz pasiva

  • La voz pasiva vuelve ambiguo al agente de la acción y hace que la oración sea menos clara.
  • Cambiarla a voz activa hace que la oración sea más clara y fácil de entender.

• No uses adverbios

  • En lugar de adverbios, usa verbos más específicos o añade una explicación.
  • Los adverbios a menudo no transmiten con precisión el significado al lector y dejan ambigüedad.

• No des por sentado el conocimiento

  • Proporciona el contexto adecuado sobre la información que el lector podría no conocer.
  • Cuando uses una sigla por primera vez, escríbela completa y añade una explicación.

• Sé consciente del tono

  • El tono del texto debe ser coherente, sin mezclar un tono cercano con uno formal.

• Evita la jerga y los clichés

  • Usa expresiones precisas para que el lector pueda entender con facilidad.
  • La jerga puede ser difícil de entender si el lector no pertenece a un grupo específico.

• Aprovecha el espacio en blanco

  • Divide los párrafos largos y usa subtítulos, listas, tablas, etc., para mejorar la legibilidad.
  • Destaca el contenido importante en negritas para que el lector no pase por alto los puntos clave.

Conclusión

• Los principios básicos de la edición son transmitir el significado con claridad y eliminar las palabras innecesarias.
• Siguiendo estos principios, se puede desarrollar un estilo y preferencias propios.
• El objetivo de editar es reflexionar sobre el uso del lenguaje y tomar decisiones adecuadas para comunicar el mensaje.

Opinión de GN⁺

• Mantener el propósito y la coherencia del texto durante el proceso de edición es un principio importante para cualquier tipo de escritura.
• El uso de la voz pasiva es un estilo que debe evitarse especialmente en la documentación técnica, y pasar a la voz activa contribuye a mejorar la claridad.
• Evitar el uso de adverbios y emplear expresiones concretas es eficaz no solo en la documentación técnica, sino en cualquier tipo de escritura.
• Proporcionar contexto sobre información que el lector podría no conocer es especialmente importante en la documentación técnica, ya que mejora la comprensión y la accesibilidad del documento.
• Usar espacio en blanco y separación visual es un elemento importante para mejorar la legibilidad del contenido en línea.

[GN⁺]

Opiniones en Hacker News

• Resumen del primer comentario:

  • El autor dice que se siente honrado de que su texto haya resonado con tanta gente.
  • Siguió su curiosidad y se convirtió en ingeniero de software, pero después de trabajar varios años extraña un rol más centrado en la escritura.
  • Está buscando un puesto que combine habilidades técnicas y capacidad de comunicación, y se le puede contactar a través de su sitio web y LinkedIn.

• Resumen del segundo comentario:

  • Resulta incómodo usar abreviaturas en documentación técnica sin presentarlas antes.
  • En la documentación de proyectos, se repiten y, cuando cambian los miembros del equipo, puede que ya no quede nadie que sepa qué significan.
  • A veces la única solución termina siendo tratarlas como nombres propios y seguir usándolas así.

• Resumen del tercer comentario:

  • Como revisor de documentación técnica, ha usado muchas guías de estilo.
  • Sugiere además no llamar a la misma cosa con nombres distintos.
  • Cuando hay varios autores, la terminología puede variar y confundir a los lectores.

• Resumen del cuarto comentario:

  • No está de acuerdo con el consejo de "evitar la voz pasiva".
  • La voz pasiva es una herramienta que puede cambiar la perspectiva sobre una acción.
  • Al usarla, se puede elegir si mencionar o no el origen de la acción.

• Resumen del quinto comentario:

  • Es difícil decidir para quién se está escribiendo.
  • Hay que considerar distintos tipos de lectores, como técnicos, generales y no técnicos.
  • Vive un conflicto entre intentar que el texto sea accesible para más lectores y al mismo tiempo reducir su extensión.

• Resumen del sexto comentario:

  • Expresa entusiasmo por mejorar la escritura.
  • Da consejos sobre la importancia de usar listas y sobre cómo usarlas de forma adecuada.

• Resumen del séptimo comentario:

  • Sugiere evitar el uso de la palabra "just".
  • "Just" implica simplicidad, pero en realidad puede no ser así.

• Resumen del octavo comentario:

  • Destaca la importancia del espacio en blanco no solo en documentación técnica, sino también en blogs, correos electrónicos y otros textos.
  • Los párrafos largos son difíciles de leer y hacen que la gente pierda la atención con facilidad.

• Resumen del noveno comentario:

  • Al haber trabajado antes en un MSP, reconoció la importancia de las guías de producción bien redactadas.
  • Tomando como referencia su experiencia en periódicos, busca lineamientos que puedan ayudar en la redacción de documentación.

• Resumen del décimo comentario:

  • Sugiere evitar el uso del tiempo futuro.
  • En documentación, es mejor decir "si haces esto, pasa esto" en lugar de "si haces esto, pasará esto".