Pagué a personas para intentar seguir mi README

Artículo original ↗ Discusión en Hacker News ↗

Pagar a personas para seguir el README de un proyecto como si fuera un guion revela cuántas suposiciones, omisiones y distracciones se cuelan en la documentación para desarrolladores. Los comentaristas sostienen que los READMEs deberían decir claramente qué hace el software, listar los prerrequisitos y ofrecer una ruta mínima y completa de configuración, y muchos critican el exceso de emojis, los chistes internos y la “bazofia” generada por IA que oscurece la información esencial. Varios señalan que este tipo de pruebas con usuarios reales se parece a las prácticas de usabilidad de UX y complementa las comprobaciones automáticas o las revisiones con LLM, que todavía no pueden juzgar la claridad, el aburrimiento o la confusión como lo hacen los humanos.

Reacción general a “pagar a personas para seguir mi README”

  • Muchos ven esto como una prueba de usabilidad estándar aplicada a documentación técnica.
  • Varios elogian la idea y dicen que prácticas internas similares (incorporar a nuevas contrataciones mediante un README, registros de fricción) detectan muchos problemas rápidamente.
  • Algunos sostienen que a menudo puedes detectar la mayoría de los problemas tú mismo siguiendo estrictamente tus propias instrucciones en una máquina limpia.

Nivel de detalle y prerrequisitos

  • Existe una fuerte sensación de que los READMEs suelen omitir pasos críticos “cero” (por ejemplo, instalar php-fpm, runtimes o herramientas).
  • Hay consenso en que una sección clara de “Prerrequisitos” es clave, aunque no expliques cómo instalar cada dependencia.
  • Hay debate sobre hasta dónde retroceder: algunos quieren comandos desde git clone en adelante; otros señalan que no puedes enumerar cada sistema operativo/gestor de paquetes.

Estilo: concisión, estructura y qué hace el software

  • Queja frecuente: READMEs que nunca explican con claridad qué hace el proyecto, solo cómo instalarlo o listar palabras de moda.
  • Muchos prefieren READMEs breves y orientados a tareas que actúen como punto de entrada a documentación más rica, en lugar de largas “novelas” o FAQ.
  • Marcos como Diataxis y la separación entre tutorial y referencia se consideran útiles para estructurar la documentación.

Tono: emojis, chistes y personalidad

  • El uso excesivo de emojis está ampliamente mal visto; muchos asocian los READMEs llenos de emojis con contenido generado por LLM o con infantilidad.
  • El humor ligero es aceptable para algunos si no oscurece el significado; otros sostienen que los chistes y las referencias culturales específicas confunden y no merecen el riesgo.
  • Varias personas señalan que lo que le resulta gracioso al autor a menudo no le llega al lector.

Humanos vs. IA/agentes en pruebas de documentación

  • Varios sugieren que los LLM y los agentes son buenos para:
    • Seguir instrucciones paso a paso en entornos aislados.
    • Señalar pasos faltantes e inconsistencias.
  • Pero se considera que los humanos son esenciales para:
    • Juzgar el aburrimiento, la claridad y la UX general.
    • Exponer suposiciones, lenguaje confuso y lagunas culturales/de conocimiento.

Fricción de instalación y automatización

  • Muchos lamentan proyectos que no “simplemente funcionan”, incluso con READMEs.
  • La containerización (Docker) y las herramientas de entorno (Nix, direnv) reciben elogios por configuraciones reproducibles y de baja fricción.
  • Algunos sostienen que el software verdaderamente pulido debería automatizar la configuración en lugar de depender fuertemente de READMEs manuales.