Escribir para lectores
Tu lector no estuvo allí. Conoce el campo, no tu proyecto, y hojea. Para la elección de palabras, aplica plain-words.
- Editar, corregir o limpiar un artículo, informe o página existente: sigue
references/editing-pass.md, con las reglas a continuación como lista de verificación. - Escribir o editar un artículo académico: lee también
references/paper.md.
Orden
- Empieza con el hallazgo: qué pasó y qué tan grande. Titula la nueva idea o capacidad; una comparación solo lidera cuando es la contribución. Abre con el problema solo si es necesaria una introducción; nunca una genérica. No narres el historial del proyecto ni un registro de lo que se ejecutó.
- Los títulos enuncian la afirmación en un informe ("Planes más baratos venden más", no "Análisis de precios"); un informe largo abre con una lista numerada de hallazgos.
- Los resúmenes y TL;DRs se mantienen a alto nivel: hallazgos en palabras, el número que el lector citaría, nulos en palabras, por qué importa cada uno. Coincide con la longitud solicitada. Termina con una afirmación sencilla que el lector recordará.
- Correos electrónicos y traspasos son una lista breve de decisiones: qué hacer, qué tan difícil es cada arreglo, qué opción requiere menos trabajo manual.
- El texto principal es autónomo. Define cada término y comparador donde aparece por primera vez, nunca primero en un apéndice. Un informe largo termina con un glosario breve.
Contenido
- Da a cada número algo con qué compararlo: "25,6% de precisión (el azar es 10%)".
- Di qué tan grande es un hallazgo, incluso cuando es pequeño.
- Muestra un ejemplo real por hallazgo. Mantén casos de estudio, sorpresas y resultados negativos verificados.
- Explica un método una vez, donde aparece por primera vez: una línea sobre el cómo; el porqué solo donde el lector preguntaría o sería engañado. Revela exclusiones que definen la población o el denominador; no defiendas elecciones rutinarias.
- Sin advertencias de contenido ni notas sobre tu propio proceso a menos que el medio o el usuario las solicite. Si se eligió un umbral o subconjunto después de ver los resultados, establece la regla claramente, una vez.
- Menciona una limitación una vez, junto a la afirmación que limita, y solo si cambia lo que el lector debería creer. Mantén las condiciones que definen el resultado ("solo en 2024"). Un casi-acierto bajo una verificación de robustez no degrada un titular; una reversión sí.
- Acota una sobreafirmación en lugar de atenuarla: conserva la parte firme, elimina la parte dudosa.
- No sabotees el hallazgo. No concedas nada más allá de lo que muestran los datos. No agregues un contraste que nadie pidió a menos que cambie lo que el lector debería creer. Si una verificación debilita una historia, propón arreglar o extender el análisis antes de atenuarlo o descartarlo; no cambies el análisis tú mismo.
- Sin bloques densos. Un párrafo hace un punto y se puede leer de una vez, a velocidad. Divide un párrafo que acumule hallazgos o condiciones; una serie de números va en una tabla o una lista. Las viñetas están bien cuando los elementos son paralelos.
- Una sola historia. Elimina historias secundarias. Las verificaciones secundarias y excepciones reciben una oración en el texto principal; su detalle va a un apéndice.
- Compara cosas comparables. Números de diferentes conjuntos de datos o personas tienen su propia oración o tabla. Nunca los coloques uno al lado del otro como si uno causara el otro.
- Todo debe justificarse. Cada palabra, oración, párrafo, elemento de lista, sección, columna de tabla, panel de figura y cláusula de pie de foto debe cambiar lo que el lector cree o cómo lee algo. Pregunta de cada uno: ¿qué perdería el lector sin ello? Si nada, córtalo; no lo comprimas.
- Di cada cosa una vez. Un número vive en una tabla o en el texto, no en ambos; en el texto principal o en el apéndice, no en ambos. Un hallazgo se expresa completo una vez; el resumen, la introducción y el resumen ejecutivo solo repiten su número clave.
- No agregues nada que no esté en las fuentes. Nunca inventes una cita o un resultado; deja un marcador visible para el autor.
Figuras y tablas
- Cada panel hace un punto que el texto no puede hacer igual de bien. Haz que la métrica, la dirección mejor y las líneas base sean obvias.
- Nombres reales, no códigos; el gráfico más simple; ejes titulados; un esquema de etiquetas, que coincida con el pie de foto y el texto. Coloca una etiqueta directa junto a la serie que nombra.
- Muestra todos los subconjuntos, o indica la regla que los seleccionó.
- En un informe, el título de la figura dice qué se muestra. El pie dice cómo leerlo y no repite los métodos.
Antes de entregarlo
Léelo como el lector. Por cada oración: ¿la echarían de menos? ¿Cada número dice "comparado con qué"? Luego ejecuta plain-words. No cambies ningún número. Si falta algo o dos números no coinciden, informa al autor en lugar de llenar el vacío.