Por qué el onboarding de ingeniería vía README siempre se pudre
Cualquier README de onboarding se pudre en dos trimestres. La falla es estructural, no editorial, y reescribirlo con más esfuerzo no la corrige.
- Tiempo a primer PR mergeado
- 1 semana
- DMs de Slack en semana 1
- 1
- "Esto debería funcionar"
- 17 veces
- Setup completado sin ayuda
- 90%
Lo esencial.
Un README es un solo documento que pretende ser el registro canónico de cada paso que necesita un nuevo ingeniero para empezar a trabajar. El patrón falla de una forma muy específica: se pudre en dos trimestres, y la pudrición no es un problema de redacción. Es un problema estructural, porque un solo archivo tiene que seguir un sistema que cambia todos los días entre versiones de Postgres, versiones de Node, certificados SSL, túneles VPN, variables de entorno y los cuatro scripts en `bin/` que nadie tiene a su cargo. Reescribir el README con más fuerza compra dos semanas limpias y luego regresa la misma pudrición. La salida es dejar de tratar el onboarding como un documento.
Los 17 lugares donde el README miente
Un README no miente por mala fe. Miente porque cada afirmación que contiene tiene una vida media más corta que la cadencia de revisión del archivo. La frase "esto debería funcionar" aparece diecisiete veces en el README de 2,400 líneas que Mauricio, staff engineer en una plataforma de observabilidad B2B, reemplazó el trimestre pasado. Cada ocurrencia marcaba un punto donde el autor se había quedado sin paciencia para un caso límite.
El catálogo siguiente viene del historial de diffs de un README real de onboarding en un equipo Serie B de sesenta y cinco ingenieros.
| Tipo de mentira | Frase típica | Lo que era cierto | |
|---|---|---|---|
| 1 | Drift de versión | "Instalar Node 18" | Node 20.6 mínimo, 18 truena con un decorator de TypeScript |
| 2 | Herramienta reemplazada | "Correr make build" | Makefile eliminado en Q2, sustituido por un script de Bun |
| 3 | Silencio de configuración | "Agregar las variables de entorno" | Cuatro variables sin documentar bloquean el servidor de desarrollo |
| 4 | Captura de pantalla vencida | Screenshot viejo de la consola de AWS | Consola rediseñada, el botón ahora vive en otro menú |
| 5 | Suposición de OS | "Brew install Postgres" | En Linux se necesita apt, no hay ruta alterna documentada |
| 6 | Suposición de red | "El VPN debería conectarse" | El firewall corporativo bloquea el intercambio de cert en macOS Sonoma |
| 7 | Orden equivocado | Pasos 4 y 5 invertidos | Correrlos en el orden listado corrompe la base de datos local |
| 8 | Hueco de permisos | "Deberías tener acceso" | Las nuevas incorporaciones reciben acceso al día tres, no al día uno |
| 9 | Drift de rama | "Hacer checkout a main" | La rama por defecto pasó a trunk hace seis meses |
| 10 | Ruta de secretos | "Sacarlo del vault" | La ruta cambió, el comando CLI ahora exige un flag |
| 11 | Medio paso | "Correr las migraciones" | El script de migración requiere un flag que el README omite |
| 12 | Dependencia fantasma | Nada de Redis | Sin Redis corriendo, el servicio de auth crashea en silencio |
| 13 | "Debería" sin verificar | "Esto debería funcionar" | No funciona, la falla es silenciosa y los logs salen vacíos |
| 14 | Cambio de proveedor | "Llaves de prueba de Stripe" | Sandbox de Stripe sustituido por un mock interno |
| 15 | Script en bin/ | "Correr bin/setup" | El script no se ha tocado desde 2023 y asume Python 2 |
| 16 | Referencia rota | "Ver la guía de despliegue" | La guía fue eliminada en una limpieza de Confluence |
| 17 | Sesión de navegador | "Login en localhost" | El cert auto-firmado lo bloquea Chrome sin override manual |
make build"main"trunk hace seis mesesbin/setup"Cada mentira es chica. La suma transforma la primera semana de una nueva incorporación en una excavación arqueológica. La historia de documentación del equipo de ingeniería en la misma plataforma lo midió: cada nueva incorporación chocaba con seis de estas fallas en la semana 1.
Por qué reescribir el README nunca funciona
Tres ingenieros habían intentado reescribir el README en el año previo a que Mauricio grabara el setup. Cada reescritura era excelente durante dos semanas. Después se pudría. El patrón no tiene que ver con disciplina ni con talento de redacción. Es estructural, y se puede predecir la falla sin conocer al equipo.
Un README tiene un solo autor en cada momento. La primera reescritura ocurre cuando el costo de la pudrición se vuelve visible (una semana de DMs a seniors por cada nueva incorporación). Alguien levanta la mano, bloquea dos días, saca un archivo sólido y lo mergea. La semana siguiente, una herramienta sube de versión, un script cambia, se agrega una variable de entorno. El autor original ya pasó a otra cosa. El cambio no se replica porque el costo de editar el archivo es mayor que el costo de escribir la respuesta en un DM de Slack a quien pregunta. La pudrición arranca de nuevo en la semana 3.
Compárelo con la forma en la que el código se mantiene al día. El código no se pudre al mismo ritmo porque el build truena cuando el código se desincroniza. El README es un artefacto de solo lectura desde la perspectiva del build. Nada falla cuando el README se desfasa. La investigación de NNGroup sobre por qué los usuarios escanean en lugar de leer describe el patrón dominante: los lectores escanean, no leen completo, y le dan menos crédito al documento con cada afirmación falsa que encuentran. Para cuando la nueva incorporación va por la tercera mentira, cierra el archivo y abre un DM. El senior responde porque responder 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 costo de mantenimiento lo carga una persona y el costo de la falla lo carga otra, y esa asimetría hace que la pudrición sea inevitable. Reescribir no cambia la asimetría. Compra dos semanas y resetea el reloj.
El camino que sí funciona alinea al mantenedor con quien cambia la herramienta: quien modifica un script vuelve a grabar el paso afectado en dos minutos, sin sprint de documentación. Eso es exactamente lo que plantea el flujo de grabación de la extensión de Chrome.
Qué reemplaza a un README
Lo que reemplaza a un README son doce guías cortas, una por modo de falla, grabadas por el ingeniero que resolvió esa falla 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 directo: el tiempo a primer PR pasó de tres semanas a una. Los DMs de Slack en semana 1 hacia los seniors bajaron de seis a uno por nueva incorporación. El setup terminado sin ayuda pasó de "casi nunca" a noventa por ciento. Estas métricas le permiten a un staff engineer o a un engineering manager de SaaS B2B, 50 a 200 ingenieros, defender el cambio frente al liderazgo.
La estructura es específica. Una guía principal de veintitrés pasos recorre el happy path en una laptop nueva. Cada modo de falla conocido (la versión incorrecta de Node, el cert SSL, las variables de entorno faltantes, el túnel VPN, la extensión de Postgres, los cuatro scripts bin/) tiene su propia guía corta de troubleshooting. La guía principal apunta a la guía de troubleshooting en el paso exacto donde típicamente aparece la falla. La nueva incorporación ya no escanea 2,400 líneas buscando su error. Hace clic.
La forma de cada guía importa. Los pasos están numerados. Cada uno trae una captura de la pantalla actual real, 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 las nuevas incorporaciones dejan de creerle a un documento que se lee como un volcado de comandos. La investigación de NNGroup sobre el patrón de lectura en F explica por qué este formato aguanta: el lector escanea las primeras palabras de cada renglón, mira la captura, avanza. La granularidad por paso embona con el escaneo.
Cuando una herramienta cambia, solo se vuelve a grabar el paso afectado. Dos minutos, no una refactorización del README. El costo de mantenimiento queda lo bastante bajo para que el ingeniero que hizo el cambio realmente lo cargue. El costo de falla deja de componerse porque la siguiente incorporación nunca choca con el paso vencido. El recorrido completo vive en el caso a favor de las guías paso a paso.
El costo de conservar el README
El costo de conservar el README no lo paga su autor. Lo pagan los seniors que responden DMs y las nuevas incorporaciones cuyo primer PR se atrasa quince días. Eso es lo que vuelve invisible el costo para el ingeniero que podría reescribir el archivo. La contabilidad está mal, y la mala contabilidad protege a los malos patrones.
Saquen la cuenta a sesenta y cinco ingenieros, cuatro nuevas incorporaciones por trimestre, tres semanas de ramp-up. Cada nueva incorporación genera unos seis DMs en la semana 1. Cada DM cuesta veinte minutos contando el context-switching. Eso da dos horas de tiempo de senior por nueva incorporación solo en las fallas obvias, antes de la ayuda real al setup. Cuatro nuevas incorporaciones por trimestre a dos horas cada una son ocho horas trimestrales en preguntas que una guía habría absorbido.
El costo por nueva incorporación es más nítido. Dos semanas de ramp-up bloqueado son cero PRs mergeadas en la primera quincena. A un costo cargado de USD 200,000 por senior al año (la cifra conservadora para una plataforma de observabilidad Serie B), dos semanas a cero output cuestan alrededor de USD 7,700 por nueva incorporación, cerca de MXN 154,000 al tipo de cambio actual, que la empresa se traga porque el README se pudrió. Multipliquen por cuatro nuevas incorporaciones por trimestre y la cuenta anual ronda los USD 123,000.
El costo se compone porque no aparece en ningún OKR trimestral. El impuesto de la pudrición lo paga globalmente la organización de ingeniería y no sale en la evaluación de nadie. La salida es poner el costo en quien sí puede evitarlo: quien cambia la herramienta arregla el paso, en los mismos cinco minutos. Eso es lo que cubre el plan de equipo desde 12 USD por asiento, y el cálculo justifica el gasto de manera casi sistemática durante el primer trimestre.
Existe un costo más difuso. Una nueva incorporación que recoge demasiadas mentiras en su primera semana arranca su puesto con el calibre equivocado. Aprende que la documentación es poco confiable, que las respuestas se obtienen vía DM a los seniors, que los procesos se pudren. Ese calibre es difícil de revertir cuando el liderazgo, más adelante, le pide a esos mismos ingenieros que escriban buena documentación.
Cuándo un README sigue siendo el formato correcto
Un README sigue siendo el formato correcto para lo que cambia poco y se lee completo. Tres casos califican, el resto pertenece a guías grabadas.
Primer caso: la declaración de propósito del proyecto. Qué hace el sistema, qué no hace, quién es responsable de él. Esta información se mueve una vez al año, máximo. La lectora escanea, entiende, sigue. Una frase de README es la forma correcta.
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 aplican a colaboradores ocasionales que jamás van a estar en el Slack del equipo. La lectora no tiene acceso a un workspace de Capture, no tiene un senior a quien hacerle DM, y necesita un texto autocontenido que pueda leer 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 quién le habla a quién. 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 embona con el formato README.
Todo lo que cambia más de una vez por trimestre y se lee para ejecutar no aplica. El setup del entorno de desarrollo, el flujo de despliegue, el runbook de guardia, los patrones de debug en Datadog o Grafana, las cuatro dependencias fantasma que bloquean el servicio de auth. Todo eso se pudre a la velocidad a la que cambian las herramientas subyacentes y se beneficia de una grabación por paso que se refresca en dos minutos.
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 solo archivo no puede seguir un proceso que cambia más rápido de lo que se revisa. La salida funciona igual en ambos dominios.
Preguntas frecuentes.
- ¿Cuánto tarda reemplazar un README de 2,400 líneas con guías grabadas?
Mauricio, 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 tomó alrededor de treinta minutos. El total cabe en menos de dos días-persona, más rápido que las tres reescrituras de README que el equipo había intentado antes. Detalles numéricos en la historia de documentación del equipo de ingeniería.
- ¿Quién mantiene las guías cuando el autor original pasa a otra cosa?
Quien cambia la herramienta vuelve a grabar el paso afectado. El costo de mantenimiento es de dos minutos por cambio, lo bastante bajo para que los ingenieros sí lo carguen en lugar de empujarlo a otro. El patrón aguanta porque el costo de la actualización lo paga la misma persona que detonó la necesidad, lo que elimina la asimetría que pudre un README. Una revisión trimestral atrapa los pasos que alguien olvidó volver a grabar, pero el costo por paso es lo bastante bajo para que el trimestral funcione como red de seguridad.
- ¿Y los ingenieros que prefieren leer texto en lugar de ver una guía?
Las guías de Capture no son videos. Cada paso es una captura de pantalla más una descripción escrita, exportable a Markdown, HTML o PDF. Un lector que quiere hojear lo hace de la misma forma que con un README, salvo que las capturas sí están al día. La narración es opcional y se renderea como texto alineado a cada paso. El formato optimiza para el lector que escanea, lo que la investigación de NNGroup sobre legibilidad y comprensión muestra como la forma real en que se consume la documentación técnica.
- ¿Funciona para 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 se quedan en el README porque los colaboradores externos no tienen acceso a un workspace privado. El setup del entorno de desarrollo se puede exportar a PDF o HTML y commitear al repo, lo que les da a los colaboradores externos el mismo formato escaneable sin obligar a los mantenedores a cargar un archivo de 2,400 líneas. El reparto se sostiene en dos: estático en el README, ejecutable en guías grabadas.
- ¿A partir de qué tamaño de equipo conviene hacer el cambio?
El cambio empieza a pagar alrededor de quince ingenieros, cuando el impuesto de DM-a-seniors se vuelve visible. Por debajo, el README suele mantenerlo la misma persona que lo lee. Por arriba de cincuenta ingenieros, el costo de interrumpir a los seniors rebasa lo que el formato puede absorber. El staff engineer o el engineering manager de un SaaS B2B en el rango de 50 a 200 es la persona que saca el rendimiento más nítido.
¿Listos para reemplazar su README de ingeniería con doce guías grabadas?
Capture graba el setup una sola vez en una laptop nueva, narra cada paso y exporta una guía por paso que se refresca en dos minutos cuando una herramienta cambia. El tiempo a primer PR mergeado 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 derecho y al revés se vuelve el cuello de botella. La wiki se pudre. La Loom que nadie ve 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 los docs de onboarding mueren en ocho semanas porque nadie los regraba cuando la UI cambia. La salida no es un mejor redactor. Es un método recording-first que toma 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 se acumula en su contra, y 12 pasos es el techo operativo arriba del cual el porcentaje de finalización se cae.
Graba un workflow.
Extensión de Chrome gratuita. Sin registro.