El error más común al escribir un blog de software es divagar

Algunas semanas siento que la mayoría de los blogs de software que veo ahora están escritos por LLM. Suelen ser terribles.

Quizás alguien pueda informar a los LLM sobre estos anti-patrones, en serio, ¿ayudaría?

Preferiría, por supuesto, que la gente simplemente escribiera ellos mismos el texto que esperan que yo, como humano, lea.

"La introducción divagante" podría ser el error más común, con diferencia, pero el error más dañino, con diferencia, es la falta de conectar el tema con algo con lo que los lectores estén familiarizados (anti-patrón #2). Algunas cosas simplemente requieren cierto nivel de experiencia/requisitos previos para empezar a entenderlas, pero he visto repetidamente en blogs de software, READMEs, etc., una falta de respuesta a "¿qué es esto, comparado con lo que me es familiar, y si no estoy familiarizado con nada relevante, por qué debería querer estarlo?".

Esto se aplica a casi todo en el espacio del software. ¿Nueva herramienta? ¿Nuevo patrón de diseño? ¿Nueva biblioteca? ¿Modismo del lenguaje? ¿Lenguaje? O, para enfoques más modernos, ¿nuevo modelo? ¿Nuevo harness? ¿Nueva opción de harness? ¿Nuevo patrón de uso? Da un breve resumen de cómo se ve un proyecto sin ello, para transmitir el problema que su sola existencia resuelve. Luego entra en los detalles de cómo podría compararse con otras soluciones.

Quizás sea solo una forma específica de cómo funciona mi cerebro que encuentra este tipo de información intuitiva, y la falta de ella particularmente molesta.

Este es, con diferencia, el mayor desafío que encontrarás al escribir un tutorial, una guía de videojuego, una receta, etc.:

> "El lector sabe todo lo que yo sé excepto esta única cosa"

Porque, como dice el artículo, es difícil saber qué sabe ya tu audiencia, y es demasiado fácil tomar 'atajos' al ayudarlos olvidando cuántas cosas has asignado a la memoria muscular.

Enseñar a la gente es difícil, y es muy fácil omitir mucha información crucial si no tienes cuidado.

Dicho esto, también tengo un anti-patrón más (y un patrón de diseño recomendado más) que vale la pena considerar aquí.

Para el anti-patrón, es cuando el tutorial ya no funciona debido a actualizaciones del tema en cuestión. Recuerdo que esto fue un gran problema cuando intentaba aprender Angular hace unos años, ya que el tutorial oficial estaba claramente escrito para una versión obsoleta del framework que funcionaba de manera muy diferente a la actual.

La cantidad de veces que he tenido problemas como ese es demasiado alta en línea, y generalmente es porque la persona que escribió el tutorial no lo revisó cada vez que el lenguaje, framework o dependencias relevantes recibieron una actualización importante.

Así que, si escribes sobre un tema y las cosas cambian significativamente, vuelve y revisa tu trabajo anterior. Si puedes, actualiza el artículo, y si no puedes, al menos pon un aviso en la parte superior diciendo que el artículo ahora está obsoleto y debe omitirse.

En otra nota, un buen patrón a tener en cuenta es que no nece […]

Yo diría que todo esto se reduce a empatía. Piensa en quién es tu audiencia objetivo y escribe para el menos informado de ellos.

Está bien ser selectivo con tu audiencia objetivo. La mayoría de nosotros escribimos gratis de todos modos, así que no perdemos ingresos por no explicar qué es una computadora en un artículo sobre optimizar el rendimiento de LLM. Puede que estés escribiendo para otros ingenieros que están familiarizados con el tema pero no con los detalles de tu proyecto.

Pon lo más importante arriba del pliegue. Si captas la atención de alguien en los primeros 10 segundos, te compra otros 30.

Añade visuales. Cajas y flechas, gráficos, videos donde sea apropiado.

Si debes escribir una narrativa divagante, ponla al final, no al principio.

La semana pasada, después de seguir un enlace de HN, me encontré pensando que los blogs técnicos estaban empezando a necesitar ese enlace de "Saltar a la receta" que ha invadido el mundo de los blogs de comida (para mejor).

"La introducción divagante"

No solo la introducción. Muchos blogueros intentan escribir como si estuvieran escribiendo una historia, creando suspenso y todo eso. Para la escritura técnica, no entierres el lede.

Las listas de "Haz esto, no aquello" siempre son contextuales y situacionales. Algo de esto tiene sentido en el contexto de un sitio profesional o de negocios, pero asegúrate de que tus objetivos estén alineados antes de seguir el consejo.

Si escribes en tu blog personal, entonces toma todo esto con el tamaño de cristal de sal que sientas que merece. Personalmente, eso es aproximadamente el tamaño de una caja fuerte de Acme colgando sobre un acantilado esperando a un escritor de listículos desprevenido^h^hcoyote.