Los desarrolladores suelen escribir documentación pobre, asumiendo que los usuarios comparten sus sesgos y conocimientos. Para superar esto, el autor pagó a usuarios reales 25 euros por hora para probar su README de Activity Bot siguiendo las instrucciones en voz alta mientras compartían su pantalla. Esto reveló fallos críticos: enlaces de demostración rotos, pasos confusos de renombrado de archivos, términos técnicos poco claros, mala ordenación de secciones y propósito del software sin explicar.
El autor tomó notas manuscritas, actualizó el README después de cada sesión y volvió a probar con nuevos usuarios. Tras varias sesiones, pagó 150 euros por retroalimentación franca. El proceso destacó que los usuarios reales exponen suposiciones ocultas —como la necesidad de sudo, requisitos de reinicio y reglas de citado— que los desarrolladores pasan por alto.
A diferencia de las LLMs, las personas reales aportan humor, perspectivas únicas y señales emocionales como la frustración, que indican dónde falla la documentación. El autor lo compara con su experiencia en redacción técnica de GOV. UK, donde la revisión humana convirtió un prosa florida en documentos claros y utilizables.
Aunque el README no es perfecto, ahora es demostrablemente más fácil de seguir. La lección principal: los desarrolladores deben probar la documentación con personas reales que piensen en voz alta, incluso si no están pagadas, para descubrir puntos ciegos y mejorar la usabilidad.
Fuente: Hacker News · Resumido por HeadlinesBriefing