Por qué el onboarding de ingeniería vía README siempre se pudre
Todo README de onboarding se pudre en dos trimestres. El defecto es estructural, no editorial, y reescribirlo más fuerte no arregla nada.
- Tiempo hasta la primera PR
- 1 semana
- DMs de Slack en semana 1
- 1
- "Esto debería funcionar"
- 17 veces
- Setup terminado sin ayuda
- 90 %
Lo esencial.
Un README es un documento único que pretende ser la traza canónica de cada paso útil para que un nuevo ingeniero arranque. El patrón de fallo es preciso: se pudre en dos trimestres, y la podredumbre no es un problema de redacción. Es un problema de estructura, porque un solo fichero tiene que seguir un sistema que cambia a diario, entre versiones de Postgres, versiones de Node, certificados SSL, túneles VPN, variables de entorno y los cuatro scripts en `bin/` que nadie posee. Reescribir el README más fuerte ofrece dos semanas limpias y luego vuelve la misma podredumbre. La salida consiste en dejar de tratar el onboarding como un documento.
Los 17 sitios donde el README miente
Un README no miente por mala fe. Miente porque cada afirmación tiene una vida media más corta que la cadencia de revisión del fichero. La frase "esto debería funcionar" aparece diecisiete veces en el README de 2.400 líneas que Sergio, staff engineer en una plataforma de observabilidad B2B, reemplazó el trimestre pasado. Cada ocurrencia marcaba un punto donde el autor había agotado su paciencia ante un caso límite.
El catálogo de abajo viene del diff de un README de onboarding real, serie B, equipo de sesenta y cinco ingenieros.
| Tipo de mentira | Frase típica | Realidad | |
|---|---|---|---|
| 1 | Deriva de versión | "Instala Node 18" | Node 20.6 mínimo, 18 revienta con un decorator de TypeScript |
| 2 | Herramienta sustituida | "Lanza make build" | Makefile retirado en T2, sustituido por un script de Bun |
| 3 | Silencio de configuración | "Añade las variables de entorno" | Cuatro vars no documentadas bloquean el servidor de desarrollo |
| 4 | Captura caducada | Captura vieja de la consola AWS | Consola rediseñada, el botón está en otro menú |
| 5 | Hipótesis de SO | "Brew install Postgres" | En Linux hace falta apt, no hay ruta alternativa |
| 6 | Hipótesis de red | "El VPN debería conectar" | El firewall corp bloquea el intercambio de cert en macOS Sonoma |
| 7 | Orden inverso | Pasos 4 y 5 invertidos | Ejecutarlos en el orden listado corrompe la base local |
| 8 | Hueco de permisos | "Deberías tener acceso" | Los nuevos fichajes tienen acceso al día tres, no al día uno |
| 9 | Rama por defecto | "Checkout main" | La rama por defecto pasó a trunk hace seis meses |
| 10 | Ruta de secretos | "Recupera del vault" | La ruta cambió, la CLI exige un flag |
| 11 | Medio paso | "Lanza las migraciones" | El script de migración pide un flag que el README omite |
| 12 | Dependencia fantasma | Cero mención de Redis | Sin Redis, el servicio de auth se cae sin avisar |
| 13 | "Debería" no verificado | "Esto debería funcionar" | No funciona, el fallo es silencioso y los logs están vacíos |
| 14 | Cambio de proveedor | "Claves de test de Stripe" | La sandbox de Stripe la sustituye un mock interno |
| 15 | Script bin/ | "Ejecuta bin/setup" | El script no se toca desde 2023 y asume Python 2 |
| 16 | Enlace roto | "Mira la guía de despliegue" | La guía la borraron en una limpieza de Confluence |
| 17 | Sesión de navegador | "Login en localhost" | El cert autofirmado lo bloquea Chrome sin override manual |
make build"main"trunk hace seis mesesbin/setup"Cada mentira es pequeña. La suma convierte la primera semana de un fichaje en obra de arqueología. La historia de documentación de engineering en guías en la misma plataforma lo cifró: cada nuevo fichaje se topaba con seis de estos fallos en la semana 1.
Por qué reescribir el README nunca aguanta
Tres ingenieros lo habían intentado el año anterior al trabajo de Sergio. Cada reescritura era excelente durante dos semanas. Después se pudría. El patrón no tiene que ver con la disciplina ni con el talento de redacción. Es estructural, y el fallo se predice sin conocer al equipo.
Un README tiene un autor a la vez. La primera reescritura ocurre cuando el coste de la podredumbre se vuelve visible (una semana de DMs a los seniors por cada fichaje). Alguien se ofrece, bloquea dos días, saca un fichero sólido. Lo mergea. La semana siguiente, una herramienta sube de versión, un script cambia, se añade una variable de entorno. El autor inicial ya está en otra cosa. El cambio no se propaga porque editar el fichero cuesta más que escribir la respuesta por DM en Slack a quien pregunta. La podredumbre arranca de nuevo en la semana 3.
Compara con cómo se mantiene el código. El código no se pudre al mismo ritmo porque el build se rompe cuando el código deriva. El README es un artefacto de solo lectura desde el punto de vista del build. Nada falla cuando se queda atrás. La investigación de NNGroup sobre por qué los usuarios escanean en lugar de leer describe el patrón dominante: se escanea, no se lee, y a un documento se le da menos crédito con cada afirmación falsa que se encuentra. A la tercera mentira, la nueva incorporación cierra el fichero y abre un DM. El senior contesta, porque contestar es más rápido que reescribir la línea 1.847.
La conclusión estructural es nítida. Un README es el formato equivocado porque el coste de mantenimiento lo paga una persona y el coste del fallo lo paga otra, y esa asimetría hace inevitable la podredumbre. La reescritura no cambia la asimetría. Compra dos semanas y resetea el contador.
El camino que aguanta alinea al mantenedor con quien cambia la herramienta: quien modifica un script regraba el paso afectado en dos minutos, sin sprint de doc. Eso es lo que plantea el flujo de grabación de la extensión de Chrome.
Lo que reemplaza al README
Lo que reemplaza al README son doce guías cortas, una por modo de fallo, grabadas por el ingeniero que resolvió ese fallo más recientemente. El README de 2.400 líneas de la plataforma de observabilidad fue sustituido por doce guías. Los números se leen directos: el tiempo hasta la primera PR pasó de tres semanas a una. Los DMs de Slack en semana 1 hacia los seniors cayeron de seis a uno por fichaje. El setup terminado sin ayuda pasó de "casi nunca" a noventa por ciento. Estas métricas permiten a un staff engineer o un engineering manager de SaaS B2B, 50 a 200 ingenieros, defender el cambio ante la dirección.
La estructura es precisa. Una guía principal, veintitrés pasos, recorre el happy path en un portátil recién aprovisionado. Cada modo de fallo conocido (versión equivocada de Node, certificado SSL, vars de entorno ausentes, túnel VPN, extensión de Postgres, los cuatro scripts bin/) tiene su propia guía corta de troubleshooting. La guía principal apunta a la de troubleshooting en el paso exacto donde aparece el fallo. La nueva incorporación deja de escanear 2.400 líneas para encontrar su error. Hace clic.
La forma de cada guía importa. Los pasos están numerados. Cada uno lleva una captura de la pantalla real actual, no una aproximación de hace un año. Cada uno trae el comando exacto, no una paráfrasis. La narración explica por qué existe el paso, no solo qué hace, porque un ingeniero recién llegado deja de creer en una doc que se lee como un volcado de comandos. La investigación de NNGroup sobre el patrón de lectura en F en la web explica por qué este formato sostiene: se leen las primeras palabras de cada línea, se mira la captura, se avanza. La granularidad por paso encaja con el escaneo.
Cuando una herramienta cambia, solo se regraba el paso afectado. Dos minutos, no una refundición de README. El coste de mantenimiento se queda lo bastante bajo para que el ingeniero que hizo el cambio lo asuma de verdad. El coste del fallo deja de componer porque la siguiente incorporación nunca tropieza con el paso caducado. El recorrido completo vive en el caso de las guías paso a paso.
El coste de conservar el README
El coste de conservar el README no lo paga su autor. Lo pagan los seniors que contestan DMs y los fichajes cuya primera PR resbala dos semanas. Eso es lo que vuelve invisible el coste para el ingeniero que podría reescribir el fichero. La contabilidad está mal, y una contabilidad mala protege patrones malos.
Haz el cálculo a sesenta y cinco ingenieros, cuatro incorporaciones por trimestre, tres semanas de ramp. Cada nuevo fichaje genera unos seis DMs en la semana 1. Cada DM cuesta veinte minutos cuando cuentas el context-switching. Son dos horas de senior por incorporación solo en los fallos obvios, antes de la ayuda real al setup. Cuatro incorporaciones por trimestre a dos horas cada una son ocho horas trimestrales en preguntas que una guía habría absorbido.
El coste por fichaje es más nítido. Dos semanas de ramp bloqueado son cero PRs mergeadas la primera quincena. A 200.000 $ de coste cargado por senior y año (la cifra conservadora para una plataforma de observabilidad serie B), dos semanas a cero output cuestan unos 7.700 $ por incorporación, alrededor de 7.100 €, que la empresa se traga porque el README se pudrió. Multiplica por cuatro fichajes trimestrales y la cuenta anual ronda los 123.000 $.
El coste compone porque no aparece en ningún OKR trimestral. La tasa de podredumbre la paga la organización de engineering en agregado y no sale en la review de nadie. La salida consiste en poner el coste sobre quien puede evitarlo: quien cambia la herramienta, corrige el paso, en los mismos cinco minutos. Eso es lo que cubre el plan equipo desde 12 $ por puesto, y el cálculo justifica casi siempre el gasto en el primer trimestre.
Hay un coste más difuso. Una nueva incorporación que recoge demasiadas mentiras en la semana 1 arranca su puesto con la calibración equivocada. Aprende que la doc no es de fiar, que las respuestas se sacan por DM a los seniors, que los procesos se pudren. Esa calibración cuesta de revertir cuando la dirección pide más tarde a esos mismos ingenieros que escriban buena doc.
Cuándo un README sigue siendo el formato correcto
Un README sigue siendo el formato correcto para lo que cambia rara vez y se lee entero. Tres casos cuadran, el resto pertenece a las guías grabadas.
Primer caso: la declaración de propósito del proyecto. Lo que el sistema hace, lo que no hace, quién lo posee. Esta información se mueve una vez al año como mucho. La lectora escanea, entiende, sigue. Una frase de README es la forma adecuada.
Segundo caso: la guía de contribución de un proyecto open source. Estilo de código, convención de ramas, formato de PR en GitHub, contributor license agreement. Estas reglas se aplican a colaboradores puntuales que nunca van a estar en el Slack del equipo. La lectora no tiene acceso a un workspace de Capture, no tiene un senior al que escribir un DM, y necesita un texto autocontenido legible directamente en GitHub. El README es el vehículo correcto aquí.
Tercer caso: la vista de arquitectura de alto nivel, el diagrama global y la descripción de qué servicio habla con cuál. Este documento cambia cuando cambia la arquitectura, una o dos veces al año en un sistema estable. Se lee para entender, no para ejecutar, y el patrón de lectura única encaja con el formato README.
Todo lo que cambia más de una vez al trimestre y se lee para ejecutar no aguanta. Setup del entorno de desarrollo, flujo de despliegue, runbook de guardia, patrones de debug en Datadog o Grafana, las cuatro dependencias fantasma que bloquean el servicio de auth. Todo eso se pudre a la velocidad de las herramientas subyacentes y se beneficia de un registro por paso que se refresca en dos minutos. La diferencia entre los dos formatos también la documenta la investigación de NNGroup sobre legibilidad y comprensión lectora, que muestra que el lector técnico optimiza por escaneo, no por lectura lineal.
Una segunda lectura sobre este reparto vive en cómo documentar el flujo de onboarding de clientes, que defiende el mismo argumento en otro dominio. El defecto estructural es idéntico: un fichero único no puede seguir un proceso que cambia más rápido de lo que se revisa. La salida funciona en ambos lados.
Preguntas frecuentes.
- ¿Cuánto se tarda en sustituir un README de 2.400 líneas por guías grabadas?
Sergio, staff engineer en la plataforma de observabilidad B2B, grabó la guía principal de veintitrés pasos en unas cuatro horas, narración incluida. Cada una de las seis guías de troubleshooting se llevó alrededor de treinta minutos. El total cabe por debajo de dos jornadas de una persona, más rápido que las tres reescrituras de README que el equipo había intentado antes. Cifras detalladas en la historia de documentación de engineering en guías.
- ¿Quién mantiene las guías cuando el autor original se va?
Quien cambia la herramienta regraba el paso afectado. El coste de mantenimiento es de dos minutos por cambio, lo bastante bajo para que los ingenieros lo asuman de verdad en lugar de empujarlo a otro. El patrón aguanta porque el coste de la actualización lo paga la misma persona que disparó la necesidad, lo que elimina la asimetría que pudre un README. Una revisión trimestral atrapa los pasos que alguien olvidó regrabar, pero el coste por paso es lo bastante bajo como para que el trimestral sea solo una red de seguridad.
- ¿Y los ingenieros que prefieren leer texto antes que mirar una guía?
Las guías Capture no son vídeos. Cada paso es una captura más una descripción escrita, exportable a Markdown, HTML o PDF. Una lectora que quiera ojear lo hace igual que con un README, salvo que las capturas sí están al día. La narración es opcional y se renderiza como texto alineado a cada paso. El formato optimiza para el lector que escanea, que es como NNGroup describe el consumo real de doc técnica. La compatibilidad con Tango y Scribe se trata en nuestras comparativas, para equipos que quieran calibrar contra alternativas conocidas.
- ¿Funciona en un proyecto open source con colaboradores externos?
Parcialmente. La vista de arquitectura, la guía de contribución y la declaración de propósito siguen en el README porque los colaboradores externos no tienen acceso a un workspace privado. El setup del entorno de desarrollo se exporta a PDF o HTML y se incluye en el commit del repo, lo que da a los colaboradores externos el mismo formato escaneable sin obligar a los mantenedores a sostener un fichero de 2.400 líneas. El reparto cabe en dos: estático en el README, ejecutable en las guías grabadas.
- ¿A partir de qué tamaño de equipo compensa el cambio?
El cambio empieza a pagar alrededor de quince ingenieros, cuando la tasa de DMs a los seniors se vuelve visible. Por debajo, el README suele mantenerlo la misma persona que lo lee. Por encima de cincuenta, el coste de interrumpir a los seniors supera lo que el formato puede compensar. El staff engineer o el engineering manager de un SaaS B2B en la franja 50 a 200 es la persona que saca el rendimiento más limpio.
¿Listo para sustituir vuestro README de engineering por doce guías grabadas?
Capture graba el setup una vez en un portátil recién aprovisionado, narra cada paso y exporta una guía por paso que se refresca en dos minutos cuando una herramienta cambia. El tiempo hasta la primera PR pasa de tres semanas a una en el caso estudiado.
Guías paso a paso: seis equipos, una sola mecánica
La persona senior que conoce el workflow al dedillo se convierte en el cuello de botella. El wiki se pudre. La Loom que nadie mira se acumula en una carpeta. Las guías paso a paso rompen ese patrón en los seis equipos que hemos visto hacerlo en producción.
Cómo documentar un flujo de onboarding de clientes en 2026
La mayoría de las guías de onboarding caducan en ocho semanas porque nadie las regraba cuando la UI cambia. La salida no es un mejor redactor. Es un método recording-first que cuesta diez minutos por actualización.
La regla de los 12 pasos: por qué la longitud predice el fracaso
Casi todo equipo de documentación escribe guías más largas de lo que debería. La longitud juega en tu contra, y 12 pasos es el techo operativo a partir del cual la tasa de finalización se desploma.
Graba un workflow.
Extensión de Chrome gratuita. Sin registro.