Relleno

• ¿Se han eliminado las transiciones de relleno? (“Es importante tener en cuenta que”, “¿Por qué hicieron esto?”, “Así es como podemos resolver este problema”). A veces, son necesarias para la fluidez, pero la mayoría se pueden eliminar. “Es importante tener en cuenta que” es la frase de relleno más usada en exceso en la escritura técnica. No la uses.
• Si algo es importante, explica por qué lo es. Tu explicación debe ser lo suficientemente convincente como para hacer que sea obvio que el tema es importante.
• ¿Hay alguna información trivial que se pueda eliminar?
• ¿Hay oraciones repetidas que no enfatizan las ideas centrales? Está bien repetir ideas centrales desde diferentes ángulos, pero las ideas secundarias no deben repetirse.
• ¿Alguna palabra de relleno u oración de relleno?
• Evita escribir cualquier cosa que suene promocional. En general, las siguientes palabras y frases no deben usarse porque son subjetivas y no transmiten información medible, útil o procesable:
  • “novedoso”
  • “innovador”
  • “desatar”
  • “gran avance”
  • “revolucionario”
  • “pionero”
  • “disruptivo”
  • “escalable”
  • “empoderador”
  • “adopción”
  • “abre posibilidades”
  • “sin igual”
  • “crea oportunidades”
  • “transformador”
  • “revelador”
  • “visionario”
  • “rompedor”
  • “tiene potencial”
  • “encabezar”
  • “estimado”
  • “ambicioso”
  • “próspero”
  • “de vanguardia”
• Elimina el lenguaje de ventas. Es una pérdida de tiempo para el lector.

Ejemplos convincentes

• ¿Podría el artículo beneficiarse de ejemplos útiles y convincentes? Un ejemplo convincente explica el algoritmo sin mostrar los pasos. Por ejemplo: divWadUp(2,3) → 0.66667, divWadDown(2,3) → 0.66666
• Añade ejemplos del mundo real siempre que sea posible.
• Proporciona contexto histórico a las decisiones de diseño cuando sea factible.
• Los conceptos abstractos requieren muchos ejemplos para explicarse claramente. Proporciona suficientes ejemplos para que el lector pueda formar un patrón en su mente.

Redacción mejorada

• ¿Se podría acortar una oración sin perder información?
• ¿Se puede dividir una oración en dos?
• ¿Se puede reducir el número de cláusulas en la oración?

Proporcionar contexto a los hechos

• ¿Está motivada la información (es decir, ¿por qué debería importarme?)?
• ¿Hay hechos muy similares con los que el escritor pueda hacer una analogía?
• ¿Muestra el escritor cómo un hecho presentado se relaciona con el tema en cuestión?

Citas y otros tutoriales

• ¿Tiene el artículo al menos una perspectiva única, o simplemente estás repitiendo lo que ya existe? Está bien resumir el trabajo de otras personas para tu propio beneficio personal, pero no ayuda a otras personas. Cuanto más luches con un problema poco documentado, más te lo agradecerán otros lectores.
• Si el artículo toma prestada otra explicación o ejemplo, ¿lo cita?

Flujo del artículo y encabezados

• ¿Le dice la introducción al lector qué esperar del artículo?
• ¿Están ordenadas topológicamente las dependencias de información? Es decir, cualquier discusión que asuma conocimientos previos debe ir después de que se expliquen dichos conocimientos.
• ¿Hacer referencia a código o información pasada requiere que los lectores se desplacen hacia arriba y hacia abajo? ¿Pueden los lectores digerir el ensayo sin desplazarse hacia arriba en una pantalla grande?
• Si tienes una dependencia circular en los temas discutidos, indica explícitamente dónde esperas que el lector se confunda y dile que espere a una sección posterior.
• Si los lectores solo leyeran por encima los encabezados, ¿seguirían teniendo una buena idea de lo que está sucediendo? Los malos encabezados incluyen “Ejemplo”, “Línea 20”.
• ¿Siguen los encabezados una jerarquía?
• ¿Hay alguna transición de tema que carezca de encabezado?
• ¿Están los párrafos divididos adecuadamente, sin muros de texto?

Público objetivo

• ¿Se mantiene constante el nivel de complejidad / nivel del lector?
• No asumas que el lector necesita que le enseñen reentrancia en un momento, para luego esperar que entienda por qué Ethereum agregó el precompile del hash Blake al siguiente. Si no estás seguro, intenta escribirle a tu yo del pasado en un momento determinado en el tiempo, es decir, hace 3 meses, hace 6 meses, hace un año, etc.

Contenido del artículo

• ¿Se ha eliminado o pospuesto para otro artículo la información fuera de tema?
• Evita desviarte por “tangentes interesantes” a menos que sean entretenidas o directamente útiles.
• Después de leer el artículo, ¿da la sensación de que falta alguna idea o explicación principal?
• Todas las ideas deben estar conectadas. No debería haber ninguna información fuera de tema ni ejemplos sin justificación. ¿Explica el artículo cómo se relacionan entre sí todos los temas discutidos?

Bloques de código y fórmulas matemáticas

• Si corresponde, ¿es fácil copiar y pegar el código?

• Si el código está destinado a ser copiado y pegado, ¿se informa al lector de los requisitos previos necesarios para que el código se ejecute correctamente?

• Si el código no está destinado a ser copiado y pegado, una captura de pantalla generalmente será mejor.

• ¿Son fáciles de leer las capturas de pantalla de código? ¿Menos espacio en blanco y fuente grande?

• Si hay una salida esperada de la ejecución de un programa, ¿hay una captura de pantalla de ella?

• ¿Las explicaciones de código proporcionan una intuición o se ejecutan de manera simbólica? NO EXPLIQUES EL CÓDIGO LÍNEA POR LÍNEA. Intenta darle al lector una comprensión de lo que está sucediendo para que cuando mire el código, “todo tenga sentido”.

• Si necesitas hacer referencia a un número de línea, haz una captura de pantalla del código y dibuja sobre la imagen para llamar la atención sobre ella. Usa esto como ejemplo: https://www.rareskills.io/post/uniswap-v2-mint-and-burn.

• ¿Tienen los grandes bloques de código o fórmulas indicaciones visuales para señalar las partes importantes?

• Usa COMENTARIOS EN MAYÚSCULAS para llamar la atención hacia donde quieras que el lector se enfoque. Mejor aún, usa una captura de pantalla y haz anotaciones en el código.

• Haz que las derivaciones algebraicas largas sean fáciles de saltar o leer por encima.

Diagramas e Imágenes

• Una imagen vale más que mil palabras; ¿se incluyen las imágenes correctas?
• ¿Tienen las imágenes un espacio vacío mínimo (estos hacen que el contenido sea difícil de leer en dispositivos móviles)?
• ¿Se pueden leer las imágenes de forma predecible (de izquierda a derecha o de arriba a abajo)?
• Usa una fuente que sea fácil de leer en las imágenes y asegúrate de que se lean fácilmente en un dispositivo móvil.
• Las imágenes deben tener texto alternativo (alt-text) cuando se publiquen.
• Si un trabajo está describiendo algo visual, debe ser visualizado.

Minimizar la carga cognitiva

• Minimiza la cantidad de información que el lector necesita en su memoria a corto plazo: repite la información pasada si es necesario o si se espera que la información sea nueva para el lector.
• Evita hacer que el lector convierta divisas o haga cálculos matemáticos mentalmente. Evita monedas abstractas como “token A” y haz las operaciones en valor de dólares.
  • ¿Hay algo más que se pueda hacer para reducir la carga cognitiva del lector?
• Usa ejemplos numéricos obvios. No es inmediatamente obvio que 6 por 68 es 408, pero es inmediatamente obvio que 6 por 4 es 24. Vale la pena jugar con los valores en los ejemplos hasta que todos los valores presentados sean relaciones numéricas obvias.
• Las variables y otros objetos de código deben estar formateados como código.
• Evita dirigir a los lectores a otras páginas para aprender un requisito previo a menos que estés escribiendo una continuación de esos temas. Esto obliga al lector a cambiar de contexto. Resume las ideas clave dentro del artículo.
• Al referirte a una carpeta, añade una barra diagonal al final. Por ejemplo, “en el directorio src/ vemos que…”

Uso de contrafactuales y respuesta a preguntas

• Dar ejemplos de código no funcional a veces puede ser útil si explica por qué el código no funciona.
• ¿Podría algún tema beneficiarse de explicar una forma alternativa de lograr lo mismo?
• ¿Algún tema planteó preguntas que quedaron sin respuesta?
• ¿Tienen algunos temas una explicación incompleta?
• A veces, los temas se explican mejor explicando los temas que los rodean en lugar de los temas en sí mismos. Por ejemplo, es difícil motivar los “números de punto fijo” de forma aislada sin explicar también los números de punto flotante y los enteros.
• Aprovecha las oportunidades para responder preguntas como “¿Por qué es de esta manera y no de otra?”.

Terminología y Definiciones

• Evita darle al lector demasiadas definiciones no triviales en una secuencia rápida. Esto aumenta la carga cognitiva.
• Al introducir nueva terminología, defínela brevemente, incluso si la explicarás en detalle más adelante. Hacer que el lector retenga en su mente un nuevo término que no entiende aumenta la carga cognitiva.
• Si la terminología no es completamente trivial, convertirla en un subtítulo puede ser útil. De esa manera, el lector puede buscar hacia atrás y encontrarla fácilmente si la olvidó.
• Para términos clave y definiciones, evita los sinónimos. Usa el mismo término una y otra vez para que le quede claro al lector a qué te refieres.

Cómo dar buenos comentarios como revisor

• Señala las áreas que no están claras, pero donde crees que entiendes al escritor, anota con tus propias palabras lo que crees que está diciendo. Esto le dará al escritor comentarios sobre cómo el lector está interpretando sus palabras.
• Si un ejemplo es convincente o útil, señálalo para que el escritor no lo elimine más tarde.
• Si entiendes algo pero te cuesta (es decir, requiere varias lecturas), señálalo. El objetivo es hacer que las cosas sean fáciles de leer. “Me costó entender” no es una admisión de incompetencia.
• Lee el artículo en voz alta. Descubrirás más problemas de esta manera.
• No des comentarios sobre la redacción o la ortografía al principio del proceso de revisión. Céntrate primero en los comentarios de alto nivel. Idealmente, la primera ronda de comentarios debería ser de tan alto nivel que no comente directamente sobre el documento.
• Regurgitar comentarios de una herramienta como Grammarly o un chatbot es inútil excepto al final del proceso de escritura. Céntrate en los comentarios provenientes de ti como lector.
• Haz una búsqueda rápida en Google sobre el tema y pídele a un chatbot que escriba un artículo sobre el mismo asunto. Si el artículo en cuestión no proporciona ninguna perspectiva nueva, díselo al escritor. Este es el comentario más valioso que puedes dar.

Preparar un artículo técnico

• Anota lo que tu público objetivo ya sabe.
• Anota por qué quieren leer tu artículo.
• Anota las ideas principales que quieres cubrir.
• Enumera cualquier artículo existente sobre el tema y por qué crees que tu artículo aportará un valor añadido.
• Anota cualquier concepto que te resultara particularmente confuso a ti o a las personas a las que les hayas explicado el tema.
• Haz una lista de las imágenes y diagramas que crearás para planificar tu escritura en torno a ellos.

Publicado originalmente el 25 de marzo de 2024