⏱️ Lectura: 12 min
Terence Eden pagó 25 euros por hora a un puñado de desconocidos para que destrozaran el README de su proyecto, ActivityBot, frente a su cámara. El experimento, publicado en su blog el 11 de octubre de 2026 y discutido el mismo día en Hacker News, es un caso real de testing de documentación con usuarios reales: la metodología que expone justo lo que el autor no puede ver en su propio texto.
📑 En este artículo
- TL;DR
- ¿Qué es el testing de documentación con usuarios reales?
- Por qué importa
- Cómo funciona el testeo de README con voluntarios
- Ejemplos prácticos: cómo aplicar esta metodología en tu propio proyecto
- Casos de uso reales
- Errores comunes y los sesgos del autor
- Comparativa con alternativas
- Profundizando
- Preguntas frecuentes
- ¿Qué diferencia hay entre el testeo de README con usuarios reales y la revisión de colegas del equipo?
- ¿Cuánto cuesta aplicar pruebas de usabilidad en documentación con voluntarios pagados?
- ¿Sirve simular usuarios con un LLM en lugar de testeo de README real?
- ¿Cuántas sesiones de validación de documentación técnica hacen falta para encontrar los problemas principales?
- ¿Qué sesgos del autor son los más difíciles de detectar sin pruebas de documentación?
- Referencias
Cada sesión duró una hora y en total gastó alrededor de 150 euros, es decir, unas seis horas de conversación anotadas a mano. El resultado no fue menor: encontró un enlace roto, una sección entera que nadie entendía y chistes que solo confundían a quien leía por primera vez.
TL;DR
- Pagar 25 euros por hora a usuarios reales para seguir un README destapa errores que el autor nunca detecta solo.
- El protocolo de pensar en voz alta durante una videollamada revela en qué frase exacta se traba cada lector.
- Actualizar la documentación después de cada sesión y repetir con la siguiente persona convierte el testeo en un ciclo iterativo.
- Cinco usuarios bastan para encontrar la mayoría de los problemas de uso, según la investigación de Jakob Nielsen de 1993.
- Los sesgos del autor, como el vocabulario compartido o los pasos obvios, son el motivo real por el que un README falla.
¿Qué es el testing de documentación con usuarios reales?
El testing de documentación con usuarios reales es una práctica de validación en la que personas ajenas al proyecto siguen instrucciones escritas (un README, una guía de instalación, un manual) mientras piensan en voz alta, para que el autor vea en qué punto exacto se confunden, abandonan o malinterpretan cada paso.
A diferencia de una prueba unitaria, que verifica el código, estas pruebas de documentación verifican la comprensión humana del texto. El objetivo no es corregir gramática: es detectar en qué momento un lector real pierde el hilo.
Por qué importa
Todo autor sufre la maldición del conocimiento: una vez que entendés cómo funciona tu propio proyecto, es casi imposible recordar cómo se ve desde cero. Eden lo admitió en su propio blog: sabía que ciertos comandos necesitaban sudo, que -foo en realidad era --foo y que, obviamente, había que reiniciar después. Esas certezas nunca estaban escritas, porque para él eran evidentes.
Ignorar el testing de documentación no es un descuido menor: es la razón por la que tantos proyectos open source tienen un README perfecto para quien ya los usa e inútil para quien recién llega.
En GOV.UK, el servicio de contenido del gobierno británico donde Eden trabajó como redactor técnico, cada texto pasaba por un segundo editor antes de publicarse. Ese segundo par de ojos detectaba errores que ningún corrector ortográfico encuentra y, sobre todo, podía notar la frustración en la voz de quien leía. Aun así, un colega del equipo todavía comparte buena parte del vocabulario del autor; un usuario externo no.
Cómo funciona el testeo de README con voluntarios
El proyecto de Eden, ActivityBot, recibe financiamiento de la fundación NLnet, que exige evidencia de que la experiencia de instalación se probó con usuarios reales. Para cumplirlo, Eden publicó un llamado en Mastodon, reunió a unos pocos voluntarios y acordó pagarles 25 euros por hora de su tiempo.
El formato fue siempre el mismo: pidió a cada voluntario que compartiera pantalla y narrara en voz alta cada decisión antes de tomarla. Qué entendía, qué no entendía, qué le frustraba, qué le daba gracia. Eden tomaba notas a mano, sin apoyarse en ninguna herramienta de transcripción automática.
Entre los hallazgos de esas sesiones aparecieron, entre otros:
- El enlace a la herramienta de demostración estaba roto.
- Algunas personas leen el README directamente desde la terminal, no en el navegador.
- Nadie entendía qué significaba realmente “renombrar un archivo”.
- Renombrar un archivo oculto no tenía instrucciones claras.
- No quedaba claro si la herramienta de demostración debía correr en la web o en la máquina del usuario.
- Algunas partes del texto necesitaban comillas y otras no, sin que la razón fuera obvia para quien leía.
- Los chistes del autor no hacían gracia: solo generaban confusión.
- Cierta terminología técnica necesitaba explicarse antes de usarla.
- El orden de las secciones confundía a quien leía por primera vez.
- El README nunca explicaba, en una frase simple, qué hacía el software.
- Una sección que al autor le parecía fascinante resultó incomprensible para todos los demás.
Cada hallazgo entraba al README antes de la siguiente llamada, así que la siguiente persona ya no se topaba con el mismo obstáculo. El ciclo completo se ve así:
flowchart TD
A["Reclutar voluntario en redes"] --> B["Sesion de 1 hora: pantalla compartida y pensar en voz alta"]
B --> C["Autor anota cada duda a mano"]
C --> D["Actualizar el README con los hallazgos"]
D --> E{"Quedan voluntarios"}
E -->|"Si"| B
E -->|"No"| F["README validado por varios usuarios reales"]
Ejemplos prácticos: cómo aplicar esta metodología en tu propio proyecto
No necesitás un grant de NLnet para replicar el formato. Alcanza con cuatro decisiones antes de la primera sesión: a quién reclutar (gente que nunca usó el proyecto, idealmente fuera de tu círculo técnico cercano), cuánto pagar o qué ofrecer a cambio, qué vas a pedirles exactamente (leer el README y narrar cada paso) y cómo vas a registrar lo que digan.
Durante la sesión, la regla de oro es no intervenir. Si alguien se traba en un comando, el impulso natural es explicarlo en voz alta; eso arruina la prueba, porque la explicación que das en vivo nunca va a estar en el texto que lean los siguientes mil usuarios. Dejá que se traben, anotá dónde y seguí.
💡 Tip: Pedile a la persona que narre cada decisión antes de tomarla (“ahora voy a copiar este comando porque…”). Ese segundo de narración es lo que delata la suposición equivocada, no el error en sí.
Después de cada sesión, actualizá el documento de inmediato, mientras el problema sigue fresco. Eden lo hizo así: no esperó a acumular feedback de todas las sesiones, corrigió entre cada llamada. Esto importa porque evita que un mismo tropiezo se repita cinco veces antes de arreglarse.
Casos de uso reales
Los proyectos financiados por fundaciones como NLnet cada vez más piden evidencia de pruebas con usuarios como condición para liberar fondos, no solo código funcionando. Eso convierte al testing de documentación de un gesto opcional a un requisito de reporte.
Equipos de documentación técnica en empresas grandes aplican una versión más barata de lo mismo: usar a una persona recién contratada como tester involuntario de la guía de onboarding, antes de que termine de aprenderse el sistema de memoria. Una vez que esa persona domina el producto, deja de ser útil como voluntario de prueba, porque hereda los mismos sesgos que el autor original.
Mantenedores de proyectos open source más chicos suelen aplicar una variante gratuita: publicar un llamado en su propia comunidad (Discord, un foro, una lista de correo) pidiendo que alguien siga el README desde cero y reporte en qué se trabó. No siempre hace falta pagar; a veces alcanza con pedirlo con claridad y agradecerlo públicamente.
Errores comunes y los sesgos del autor
- Maldición del conocimiento: el autor da por sentado pasos que automatizó mentalmente hace meses.
- Vocabulario compartido inexistente: términos como “renombrar” significan algo distinto para quien no programa a diario.
- Sesgo de confirmación en la autorevisión: releer tu propio texto solo confirma lo que ya creés que escribiste, no lo que realmente dice.
- Humor que no viaja: un chiste interno del autor rara vez aterriza en un lector nuevo y puede distraer justo en el paso crítico.
- Suponer un único canal de lectura: no todo el mundo abre el README en el navegador, algunos lo leen con
catolessen la terminal. - Orden narrativo, no orden de uso: el autor ordena las secciones como las escribió, no como las necesita quien instala el proyecto.
Comparativa con alternativas
No todas las formas de testeo de README cuestan 25 euros por hora; existen alternativas con distintos costos y niveles de rigor.
| Opción | Cuándo usarla | Ventaja | Limitación |
|---|---|---|---|
| Usuarios reales pagados | Antes de un lanzamiento importante o una solicitud de subvención | Expone sesgos que el autor no puede ver, con reacciones genuinas | Cuesta dinero y tiempo de coordinación |
| Segundo editor interno (modelo GOV.UK) | Revisión continua de cada texto antes de publicar | Rápido, sin costo extra, disponible siempre | Comparte buena parte del vocabulario técnico del autor |
| Simulación con un LLM | Primera pasada rápida para errores obvios de redacción | Gratis y disponible en minutos | No se frustra ni reacciona como un humano real |
| Sin testeo, solo autorevisión | Casi nunca, salvo cambios triviales de una palabra | Costo cero | El autor no puede detectar sus propios sesgos |
⚠️ Ojo: a Eden le sugirieron simular usuarios con un LLM y lo rechazó. Un modelo no se frustra, no tiene un gato que camine frente a la cámara y no transmite en la voz el momento exacto en que algo deja de tener sentido.
Profundizando
La cifra de Eden no es arbitraria. Jakob Nielsen demostró en 1993 que cinco usuarios bastan para encontrar la mayoría de los problemas de usabilidad de una interfaz o un texto; sumar un sexto o un séptimo aporta cada vez menos hallazgos nuevos. Si los 150 euros que gastó Eden se dividen entre los 25 euros por hora que pagó, el resultado son unas seis sesiones, justo el rango donde la curva de hallazgos nuevos empieza a aplanarse.
El protocolo de pensar en voz alta, documentado desde hace décadas en estudios de usabilidad, funciona porque obliga a verbalizar una decisión antes de ejecutarla: el silencio es tan buena señal de un problema como la pregunta en voz alta.
El método tiene un techo real. No escala a cada commit, y pagar a usuarios por cada cambio menor sería absurdo. Eden lo reservó para el primer contacto con el proyecto, el momento donde más sesgos del autor sobreviven sin ningún filtro.
📖 Resumen en Telegram: Ver resumen
Tu próximo paso: elegí el README de un proyecto propio, grabate 15 minutos leyéndolo en voz alta como si lo vieras por primera vez y anotá cada frase donde dudaste o tuviste que releer.
Preguntas frecuentes
¿Qué diferencia hay entre el testeo de README con usuarios reales y la revisión de colegas del equipo?
Un colega comparte buena parte del vocabulario técnico del autor y por eso no detecta los mismos huecos; un usuario externo no tiene ese contexto previo y se traba exactamente donde el texto asume demasiado.
¿Cuánto cuesta aplicar pruebas de usabilidad en documentación con voluntarios pagados?
Eden pagó 25 euros por hora y gastó en total unos 150 euros para varias sesiones; el costo varía según la región y la duración de cada llamada, pero el formato no requiere herramientas caras, solo tiempo y una videollamada.
¿Sirve simular usuarios con un LLM en lugar de testeo de README real?
Sirve como primera pasada rápida para errores obvios de redacción, pero no reemplaza la reacción humana: un modelo no se frustra ni deja escuchar en la voz el momento exacto en que una instrucción deja de tener sentido.
¿Cuántas sesiones de validación de documentación técnica hacen falta para encontrar los problemas principales?
La investigación de Jakob Nielsen de 1993 sugiere que cinco usuarios ya revelan la mayoría de los problemas; Eden hizo algo similar con las sesiones que pagó a 25 euros por hora, actualizando el texto después de cada una.
¿Qué sesgos del autor son los más difíciles de detectar sin pruebas de documentación?
La maldición del conocimiento y el vocabulario compartido son los más persistentes, porque el autor no tiene forma de notarlos leyendo su propio texto: necesita a alguien de afuera que se trabe en voz alta.
Referencias
- Terence Eden’s Blog: el post original donde el autor relata haber pagado voluntarios para probar el README de ActivityBot.
- Nielsen Norman Group: la investigación de Jakob Nielsen sobre cuántos usuarios bastan para una prueba de usabilidad.
- Wikipedia: definición y metodología general del testeo de usabilidad, incluido el protocolo de pensar en voz alta.
- GOV.UK Content Design: la guía de estilo de contenido del gobierno británico que exige revisión por un segundo redactor.
- NLnet Foundation: la fundación que financia proyectos como ActivityBot y pide evidencia de pruebas con usuarios reales.
📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.
Imagen destacada: Foto de Vitaly Gariev en Unsplash
¿Te sirvió? ¿Te dio otro error? Contalo abajo: las preguntas se responden y le sirven al siguiente que llegue.
Dejar un comentario
0 Comentarios