El README que hace onboarding

Descripción

La lección anterior estableció qué documentar —lo estable, de ROI alto— y esta baja a la pieza más estable, más leída y peor hecha de casi todos los proyectos: el README. El README es el primer contacto de un dev nuevo con un sistema. Es lo primero que abre cuando clona el repo, y en los primeros minutos decide si el sistema le parece accesible o impenetrable. Un buen README responde cuatro preguntas que el dev nuevo tiene ahora mismo: qué hace el sistema (para orientarse), cómo correrlo (para tenerlo andando en su máquina), dónde están las piezas (para saber a dónde ir), y cómo contribuir (para hacer su primer cambio sin romper el proceso). Un README que responde esas cuatro convierte el onboarding en horas; un README que no —o que no existe— lo convierte en días de descubrir todo a golpes.

La tesis de esta lección es que el README no es adorno: es infraestructura de onboarding, y su valor es medible. El costo de que un dev nuevo llegue a su primer commit útil no es un número borroso —es la suma concreta de los obstáculos que enfrenta: pelear para correr el proyecto, adivinar qué módulo hace qué, configurar variables de entorno sin instrucciones, no saber cómo correr los tests—. Un buen README no "documenta" esos obstáculos; los elimina, dando la instrucción exacta que los disuelve. Esta lección ejecuta el costo de onboarding con README y sin él, y muestra que la diferencia no es cosmética: es la diferencia entre 3.5 días perdidos por dev y menos de un día, multiplicada por cada persona que entra al equipo. El README es de las piezas de doc con mayor ROI que existen —estable (cambia poco), universalmente leída (cada dev nuevo, cada vez)— y por eso su descuido es de los más caros.

Conexión con el módulo. Es la aplicación concreta de la lección 5 (documentar lo estable) a la pieza más estable de todas, y la conexión más directa con el bus factor de la lección 7: el README es lo que permite que un dev nuevo arranque sin depender de una persona. Con la analogía del módulo: el README es el manual que el dueño anterior te dejó —dónde está la llave del agua, cómo se prende el boiler— que te deja operar la casa desde el primer día en vez de descubrirla a golpes. Frontera con el resto: el README apunta a las otras piezas del sistema (al C4 para el mapa detallado, a los ADRs para el porqué), pero no las reemplaza —es la puerta de entrada, no la documentación completa—; y no re-enseñamos aquí a escribir esas otras piezas, solo cómo el README las enlaza.

Una analogía: la casa con manual contra la casa donde descubres todo a golpes

Volvamos al día que te mudas a una casa que no construiste —la analogía del módulo, ahora en su forma más concreta—, y midamos el tiempo de las dos versiones.

La casa donde descubres todo a golpes. Llegas y no hay nada. La primera noche, buscas media hora el interruptor de la sala tanteando la pared. El primer invierno, el agua sale helada y pasas una tarde entera averiguando cómo se prende el boiler —¿gas?, ¿eléctrico?, ¿dónde está el piloto?— hasta que llamas a alguien. La primera vez que se bota un breaker, apagas los veinte y los vas probando uno por uno. El primer aguacero que inunda el patio, corres buscando la llave de paso del agua que está enterrada detrás de unas macetas. Cada operación básica de la casa te cuesta horas de descubrimiento, porque nadie destiló lo que ya sabía. Y lo peor: ese costo lo paga cada persona que se muda —el siguiente inquilino volverá a buscar el interruptor media hora—.

La casa con manual. Llegas y en la cocina hay una carpeta: "El interruptor de la sala está a la derecha entrando. El boiler es de gas: perilla izquierda del garaje, piloto con el encendedor de al lado. Los breakers están etiquetados; el de la cocina es el tercero de arriba. La llave de paso del agua está en el jardín, detrás del rosal, tapa verde." En diez minutos sabes operar la casa. Cuando se bota un breaker, vas directo al correcto. Cuando se inunda el patio, cierras la llave en treinta segundos. No pagas ninguna hora de descubrimiento, porque el dueño anterior ya la pagó una vez y te la regaló destilada. Y ese regalo se hereda: se lo dejas al siguiente, que tampoco sufrirá.

Aquí está el README, exacto: es la carpeta que el dueño anterior te dejó, aplicada al sistema de software. "Cómo correr el proyecto" es "cómo se prende el boiler". "Dónde están las piezas" es "dónde está cada breaker". "Cómo contribuir" es "cómo se saca la basura, qué día pasa el camión". Sin README, cada dev nuevo descubre el sistema a golpes —pelea horas para correrlo, adivina qué módulo toca, configura a ciegas—, y ese costo lo paga cada persona que entra. Con README, el dev nuevo opera el sistema desde el primer día, porque quien estuvo antes destiló lo que aprendió y lo dejó escrito. La diferencia entre las dos casas no es que una sea mejor —es la misma casa—; es que en una el conocimiento de cómo operarla sobrevivió al cambio de dueño. Esta lección mide, en horas, cuánto vale esa carpeta.

Ejemplo trabajado: el costo de onboarding con README y sin él

Vamos a medir el tiempo hasta el primer commit útil de un dev nuevo en Mercado —el momento en que deja de estar bloqueado y empieza a aportar—. Ese tiempo es la suma de los obstáculos que enfrenta antes de poder contribuir. Tomamos seis obstáculos típicos, y para cada uno medimos cuánto cuesta sin README (el dev lo descubre a golpes) y con un buen README (la instrucción exacta lo disuelve):

# El README que hace onboarding: el primer contacto del dev nuevo. Medimos el
# tiempo hasta el PRIMER COMMIT util como la suma de los obstaculos que enfrenta.
# Un buen README no adorna: ELIMINA obstaculos (como correr el proyecto, donde
# estan las piezas, como configurar el entorno). Comparamos onboarding con y sin.
BLOCKERS = [
    # (obstaculo, horas_sin_readme, horas_con_readme)
    ("correr el proyecto localmente",    8.0, 0.5),
    ("ubicar las piezas (que hace que)", 6.0, 0.5),
    ("configurar env vars y secrets",    4.0, 0.25),
    ("saber como correr los tests",      3.0, 0.25),
    ("encontrar donde hacer el cambio",  5.0, 1.0),
    ("conocer el flujo de contribucion", 2.0, 0.1),
]

print(f"{'obstaculo':<36}{'sin README':>12}{'con README':>12}")
print("-" * 60)
without = with_ = 0.0
for name, wo, wi in BLOCKERS:
    without += wo
    with_ += wi
    print(f"{name:<36}{wo:>10.1f}h{wi:>11.2f}h")
print("-" * 60)
print(f"{'TIEMPO HASTA EL PRIMER COMMIT UTIL':<36}{without:>10.1f}h{with_:>11.2f}h")
print()
print(f"Sin README: {without:.0f} h (~{without / 8:.1f} dias de trabajo perdidos por dev)")
print(f"Con README: {with_:.1f} h (menos de un dia)")
print(f"El README ahorra {without - with_:.1f} h por dev nuevo "
      f"({without / with_:.1f}x mas rapido).")
NEW_DEVS_PER_YEAR = 6
print(f"Con {NEW_DEVS_PER_YEAR} devs nuevos al ano: ahorra "
      f"{(without - with_) * NEW_DEVS_PER_YEAR:.0f} h/ano de onboarding.")

Qué esperar. Al correr el archivo, la salida es exactamente esta:

obstaculo                             sin README  con README
------------------------------------------------------------
correr el proyecto localmente              8.0h       0.50h
ubicar las piezas (que hace que)           6.0h       0.50h
configurar env vars y secrets              4.0h       0.25h
saber como correr los tests                3.0h       0.25h
encontrar donde hacer el cambio            5.0h       1.00h
conocer el flujo de contribucion           2.0h       0.10h
------------------------------------------------------------
TIEMPO HASTA EL PRIMER COMMIT UTIL        28.0h       2.60h

Sin README: 28 h (~3.5 dias de trabajo perdidos por dev)
Con README: 2.6 h (menos de un dia)
El README ahorra 25.4 h por dev nuevo (10.8x mas rapido).
Con 6 devs nuevos al ano: ahorra 152 h/ano de onboarding.

Lee la tabla obstáculo por obstáculo, porque cada renglón es una pelea concreta que el README convierte en una instrucción.

El obstáculo más caro: correr el proyecto (8h → 0.5h). Sin README, poner el proyecto a andar en la propia máquina es una odisea: qué versión del lenguaje, qué dependencias, qué base de datos, qué servicios hay que levantar, en qué orden, qué falla y por qué. Un dev nuevo puede perder un día entero solo en esto —peleando con errores de setup que no tienen nada que ver con el trabajo real—. Un buen README lo disuelve en media hora con la secuencia exacta de comandos: "instala esto, corre este script, levanta esto, listo". No es que el dev sea más listo con README; es que no está descubriendo el setup, está siguiéndolo. Ese solo obstáculo justifica el README.

Los demás obstáculos, la misma historia. Ubicar las piezas —saber qué módulo hace qué— cuesta 6h sin README (leyendo código a ciegas) y 0.5h con un README que tenga un mapa o enlace al C4. Configurar variables de entorno y secrets: 4h de adivinar contra 0.25h con una lista de qué variables hace falta y de dónde sacarlas. Saber correr los tests: 3h contra 0.25h. Encontrar dónde hacer el cambio: 5h contra 1h (el README orienta, aunque este obstáculo depende más del código). Conocer el flujo de contribución —cómo se abren PRs, qué revisa quién—: 2h contra 0.1h. En cada caso, el patrón es el mismo: sin README el dev descubre a golpes, con README sigue una instrucción, y descubrir cuesta un orden de magnitud más que seguir.

El total: 28h contra 2.6h, 10.8 veces más rápido. Sin README, el dev nuevo tarda 28 horas —tres días y medio de trabajo— solo en llegar al punto de poder aportar; ese es tiempo puramente perdido, gastado en obstáculos que no tienen nada que ver con el problema que vino a resolver. Con README, tarda 2.6 horas —menos de un día—. La diferencia, 25.4 horas por dev, no es un lujo: es tiempo real de personas caras, multiplicado por cada persona que entra. Con seis devs nuevos al año —una rotación normal en un equipo mediano—, el README ahorra 152 horas al año: casi un mes-persona de trabajo que, sin README, se quema en onboarding a golpes. Y el README que produce ese ahorro es una pieza estable (cambia poco: cómo correr el proyecto no cambia cada semana) que se escribe una vez y rinde en cada onboarding —ROI altísimo, exactamente lo que la lección 5 predijo—.

Como barras, el contraste se ve así:

Tiempo hasta el primer commit util (horas)
  sin README  |############################  28.0h  (~3.5 dias perdidos)
  con README   |###                            2.6h  (menos de un dia)
                ────────────────────────────
  10.8x mas rapido. Con 6 devs/ano: 152h ahorradas (~un mes-persona).

Profundización: qué hace un README que de verdad hace onboarding

El experimento midió el valor de un buen README, pero no dijo qué lo hace bueno. Vale la pena bajar a lo concreto, porque la mayoría de los README fracasan por razones específicas y evitables.

Un README que hace onboarding responde, en este orden, cuatro preguntas —y el orden importa, porque es el orden en que el dev nuevo las tiene—. Primero: ¿qué es esto? Una o dos frases que digan qué hace el sistema y para quién, para que el dev se oriente antes de nada ("Mercado es el marketplace que conecta compradores y vendedores; este repo es la Internal API"). Sin esto, el dev lee comandos sin saber en qué está trabajando. Segundo: ¿cómo lo corro? La secuencia exacta y probada de comandos para tener el sistema andando en la propia máquina, incluidas las dependencias, la base de datos, las variables de entorno. Esta es la sección más importante y la más descuidada: un README cuyo "cómo correrlo" no funciona es peor que no tener README, porque promete y falla. Tercero: ¿dónde está cada cosa? Un mapa breve de las piezas —qué carpeta o módulo hace qué— o un enlace al C4, para que el dev sepa a dónde ir cuando tenga que cambiar algo. Cuarto: ¿cómo contribuyo? El flujo de trabajo —cómo se abren PRs, cómo se corren los tests, qué convenciones hay— para que el primer cambio no choque con el proceso.

El criterio que separa un buen README de uno malo es brutal y simple: ¿puede un dev nuevo, siguiendo solo el README, tener el proyecto corriendo y hacer un cambio trivial, sin preguntarle a nadie? Si la respuesta es no —si en algún punto tiene que ir a preguntar porque el README no alcanza—, el README falló en su única misión. Este criterio se puede probar: siéntate a un dev nuevo (o a ti mismo en una máquina limpia) y observa dónde se atora siguiendo el README; cada lugar donde tiene que preguntar es un hueco que arreglar. Los README fracasan casi siempre en el "cómo correrlo": tienen pasos que asumen conocimiento que el autor tenía y olvidó anotar ("obvio que primero levantas la base de datos"), o que funcionaban en la máquina del autor pero no en una limpia, o que se quedaron desactualizados cuando el setup cambió. Por eso el "cómo correrlo" debe probarse en una máquina limpia, no escribirse de memoria.

Hay una tensión con la lección 5 que conviene resolver, porque parece contradictoria. Dijimos que no se documenta lo volátil, y el "cómo correr el proyecto" podría parecer volátil (los pasos de setup cambian). ¿No debería generarse en vez de escribirse? La respuesta: el "cómo correrlo" es en realidad bastante estable —la secuencia de alto nivel (instala dependencias, levanta la base, corre el servidor) cambia poco, aunque los detalles finos evolucionen— y, más importante, la mejor versión del "cómo correrlo" sí tiende a lo generado/ejecutable: un script setup.sh o un docker compose up que es el cómo-correrlo (ejecutable, no se puede desincronizar porque si no funciona, no arrancas). El README ideal para el setup no es un párrafo de pasos que se pudren, sino una instrucción que apunta a algo ejecutable ("corre make dev") más el contexto de qué hace. Así el README hereda lo mejor de living documentation: la parte volátil del setup vive en un script que se prueba en CI, y el README solo la enmarca. La regla de lo estable se respeta: el README documenta la intención estable y delega el detalle volátil a algo ejecutable.

Un último punto sobre el vínculo con el bus factor, que la lección 7 desarrollará. El valor real del README no es solo ahorrar horas de onboarding —es que ese ahorro no depende de una persona. Sin README, el dev nuevo llega a su primer commit preguntándole a alguien del equipo (a Elena, a quien sepa), lo que significa dos cosas malas: le quita tiempo a esa persona, y hace que el onboarding dependa de que esa persona esté y tenga ganas de ayudar. Con README, el dev nuevo arranca solo, sin consumir a nadie y sin depender de nadie. El README es, en el fondo, la forma de que el conocimiento de "cómo se opera este sistema" —que normalmente vive en las cabezas del equipo— sobreviva y esté disponible sin intermediarios. Es un aporte directo al bus factor: convierte conocimiento tribal (hay que preguntarle a alguien) en conocimiento disponible (está escrito).

Errores comunes

El README que no permite correr el proyecto (el peor). Qué pasa: el README tiene una descripción bonita del sistema, quizás un diagrama, pero su sección de "cómo correrlo" no funciona —tiene pasos que asumen conocimiento, están desactualizados, o simplemente faltan—, así que el dev nuevo se atora en el setup y termina preguntando. Por qué pasa: el autor escribió el "cómo correrlo" de memoria, desde una máquina que ya tenía todo configurado, olvidando los pasos que para él eran automáticos; y nunca lo probó en una máquina limpia. Cómo detectarlo: si un dev nuevo no puede correr el proyecto siguiendo solo el README, o si el "cómo correrlo" no se ha probado desde cero en mucho tiempo, está roto. Cómo corregirlo: probar el "cómo correrlo" en una máquina limpia (o hacer que un dev nuevo lo pruebe y anote cada lugar donde se atora), y preferir un script ejecutable (make dev, docker compose up) sobre una lista de pasos que se pudre. El "cómo correrlo" es la sección más importante; si falla, el README falló.

El README que describe pero no orienta (el folleto). Qué pasa: el README explica qué hace el sistema con elocuencia —párrafos sobre la visión, la arquitectura, los valores del equipo— pero no dice cómo correrlo, dónde están las piezas ni cómo contribuir; es un folleto de marketing, no un manual de onboarding. Por qué pasa: escribir sobre la visión es más agradable y "presentable" que escribir la secuencia aburrida de comandos de setup. Cómo detectarlo: si tu README impresiona pero no permite hacer nada —correr, ubicar, contribuir—, es un folleto. Cómo corregirlo: recortar la prosa de visión a una o dos frases (qué es y para quién) y dedicar el grueso a lo accionable: cómo correrlo, dónde está cada cosa, cómo contribuir. El dev nuevo no necesita que lo inspiren; necesita arrancar.

El README que se escribió una vez y nunca se actualizó (el fósil). Qué pasa: el README fue bueno el día uno, pero el setup cambió, se añadieron piezas, cambió el flujo de contribución, y el README se quedó igual —así que ahora sus instrucciones fallan y mandan al dev nuevo por caminos muertos—. Por qué pasa: el README no está en el flujo de los cambios (nadie lo actualiza cuando cambia el setup), justo el problema de proximidad de la lección 2. Cómo detectarlo: si el README menciona pasos o piezas que ya no existen, o si los devs nuevos "saben" que hay que ignorar ciertas partes, es un fósil. Cómo corregirlo: aplicar docs-as-code (lección 3) —el README vive en el repo, se revisa en los PRs que cambian el setup, y si es posible su parte ejecutable se valida en CI (el make dev que corre en el pipeline garantiza que el "cómo correrlo" funciona)—. Un README que no se mantiene se vuelve la wiki podrida de la lección 2, con el agravante de que es lo primero que ve todo el que llega.

Ejercicios

Ejercicio 1 — Prioriza las secciones. Un equipo tiene tiempo para escribir solo una sección de su README esta semana. Las candidatas son: (a) una descripción elocuente de la visión del producto; (b) la secuencia exacta y probada de cómo correr el proyecto; (c) un glosario de términos del dominio; (d) la biografía del equipo. Usando el ejemplo del costo de onboarding, di cuál deberían escribir primero y por qué, y qué te dice esto sobre las prioridades de un README.

Ver solución

Deberían escribir primero (b) cómo correr el proyecto, sin duda. En el ejemplo, "correr el proyecto localmente" es el obstáculo más caro de todos: 8 horas sin README, la mayor sola fuente de tiempo perdido. Es también el obstáculo más bloqueante: si el dev nuevo no puede correr el proyecto, no puede hacer nada —ni explorar, ni probar, ni cambiar—, así que todo lo demás está bloqueado detrás de esto. Escribir la secuencia exacta y probada de cómo correrlo disuelve el obstáculo más grande y desbloquea todo lo demás. Es la sección de mayor ROI por lejos.

Las otras tres son mucho menos urgentes o directamente prescindibles: (a) la visión del producto es agradable pero no desbloquea nada (el dev puede aportar sin un ensayo sobre la visión); (c) el glosario ayuda pero es secundario a poder correr el sistema; (d) la biografía del equipo no ayuda al onboarding en absoluto. Lo que esto dice sobre las prioridades de un README: prioriza lo accionable y bloqueante sobre lo descriptivo y agradable. Un README se juzga por si permite hacer (correr, ubicar, contribuir), no por si se lee bonito. La regla práctica: escribe primero lo que, si falta, deja al dev nuevo atorado sin poder avanzar —y eso es, casi siempre, "cómo correr el proyecto"—.

Ejercicio 2 — El README que promete y falla. El texto dice que un README cuyo "cómo correrlo" no funciona es peor que no tener README. Explica por qué —qué daño extra causa un README con instrucciones rotas que no causaría la ausencia total de README—.

Ver solución

Un README con instrucciones rotas es peor que ninguno por varias razones concretas. Primero, hace perder más tiempo: sin README, el dev nuevo sabe que está solo y busca ayuda pronto (pregunta, explora el código); con un README que parece completo, el dev confía en él, sigue sus pasos, choca contra un error, asume que hizo algo mal, reintenta, depura el problema equivocado —pierde horas intentando hacer funcionar instrucciones que no pueden funcionar porque están rotas—, antes de rendirse y pedir ayuda. La falsa promesa lo manda por un pozo.

Segundo, destruye la confianza en toda la doc: cuando el dev descubre que el "cómo correrlo" del README no funciona, deja de confiar no solo en esa sección sino en todo el README —y probablemente en toda la documentación del proyecto—, exactamente el abismo de confianza de la lección 2. Un README roto le enseña al dev nuevo, en su primer día, que "aquí la doc no sirve, mejor pregunta"; y esa lección envenena su relación con toda la documentación futura. Tercero, es una trampa que se hereda: cada dev nuevo cae en la misma promesa rota.

La ausencia de README es honesta ("aquí no hay guía, tendrás que averiguarlo"); un README roto es una mentira ("sigue estos pasos" cuando los pasos no llevan a ningún lado). Por eso el texto insiste en probar el "cómo correrlo" en una máquina limpia: un README de setup que no se ha probado es probablemente una promesa rota esperando dañar al próximo que llegue. Mejor un README corto y cierto que uno completo y falso.

Ejercicio 3 — README y bus factor. El texto dice que el README es "un aporte directo al bus factor". Explica el mecanismo: ¿cómo exactamente un buen README sube el bus factor del sistema, y qué pasa con el bus factor cuando el onboarding depende de preguntarle a una persona en vez de leer el README?

Ver solución

El mecanismo es este: el conocimiento de "cómo se opera este sistema" —cómo correrlo, dónde están las piezas, cómo contribuir— normalmente vive en las cabezas del equipo, y cuando un dev nuevo lo necesita, se lo pregunta a alguien que sabe. Eso significa que ese conocimiento operativo depende de que las personas que lo tienen estén disponibles: si todas se van (o solo la que suele ayudar), el conocimiento de cómo arrancar el sistema se va con ellas, y un dev nuevo quedaría varado sin poder correr el proyecto. Un buen README saca ese conocimiento de las cabezas y lo pone por escrito, disponible sin intermediarios: ahora "cómo se opera el sistema" no depende de que ninguna persona en particular esté —está en el repo, lo lee cualquiera—. Eso es literalmente subir el bus factor de ese conocimiento operativo: pasa de vivir en cabezas (que se van) a estar documentado (que se queda), igual que documentar lo estable de payments subió su bus factor de 1 a 2 en la lección 1.

Cuando el onboarding depende de preguntarle a una persona, pasan dos cosas que bajan la resiliencia del sistema. Primero, esa persona se vuelve un cuello de botella y un punto de dependencia: cada dev nuevo le consume tiempo, y si esa persona se va o está saturada, el onboarding se frena —el sistema depende de ella para incorporar gente—. Segundo, el conocimiento operativo nunca se hace explícito, así que se queda en modo "tribal": todos lo saben de boca en boca, nadie lo escribió, y el día que la generación que lo sabe rota por completo, se pierde. Un onboarding que depende de preguntar mantiene el bus factor bajo (el conocimiento vive en cabezas); un onboarding por README lo sube (el conocimiento vive escrito). Por eso el README no es solo eficiencia —ahorra las 152 horas al año—; es seguro: garantiza que incorporar gente y operar el sistema no dependa de que una persona específica esté ahí para explicarlo. Es la lección 7 en miniatura, aplicada al conocimiento de arranque.

Resumen y siguiente paso

En esta lección bajaste a la pieza de doc más estable, más leída y peor hecha: el README que hace onboarding. Viste que responde cuatro preguntas que el dev nuevo tiene ahora —qué hace el sistema, cómo correrlo, dónde están las piezas, cómo contribuir— y que su valor no es cosmético sino medible. Con la casa con manual contra la casa donde descubres todo a golpes, entendiste que el README es la carpeta que el dueño anterior te dejó: te deja operar el sistema desde el primer día en vez de descubrirlo a golpes. Y lo mediste: el tiempo hasta el primer commit útil baja de 28 horas (3.5 días perdidos) a 2.6 horas con un buen README —10.8 veces más rápido—, y con seis devs nuevos al año eso son 152 horas ahorradas. Aprendiste qué hace bueno a un README (responde las cuatro preguntas, y el "cómo correrlo" funciona probado en máquina limpia), por qué un README roto es peor que ninguno (promete y falla, destruye la confianza), y cómo el README sube el bus factor al sacar el conocimiento operativo de las cabezas y ponerlo por escrito.

Antes de avanzar deberías poder: nombrar las cuatro preguntas que responde un README de onboarding; explicar por qué el "cómo correrlo" es la sección crítica y debe probarse en máquina limpia; y conectar el README con el bus factor (conocimiento tribal → conocimiento disponible).

La lección 7 sube al corazón del módulo, la idea que ha estado latiendo bajo todas las anteriores: el bus factor y compartir conocimiento. Vas a simular quién se va de Mercado y qué módulos quedan huérfanos, a identificar los puntos únicos de falla, y a comparar los seguros para subir el bus factor —documentar lo estable contra formar un segundo dueño humano—, midiendo cuál es más barato. Todo lo del módulo converge ahí: living documentation, docs-as-code, el sistema C4+ADR+arc42, documentar lo estable, el README —todo existe, en el fondo, para que el conocimiento no dependa de una sola cabeza—. La próxima lección lo hace explícito y lo mide.

Recursos

• Make a README (makeareadme.com) — una guía práctica de qué secciones lleva un buen README y por qué; útil como checklist de las cuatro preguntas de esta lección. En inglés.
• GitHub — About READMEs — la referencia de cómo el README es el primer contacto con un repo y qué se espera de él. En inglés.
• Cyrille Martraire, Living Documentation (Addison-Wesley, 2019), sobre onboarding y "guided tour" — cómo la doc de arranque (el equivalente del README ampliado) reduce el costo de incorporar gente y por qué debe vivir cerca del código. En inglés.
• The Twelve-Factor App — factor sobre build/run y dependencias explícitas — por qué un proyecto debe poder levantarse con pasos explícitos y reproducibles (la base de un buen "cómo correrlo" que no falla en otra máquina). En inglés.
• Write the Docs — sobre README y documentación de proyectos — la comunidad que sistematiza cómo escribir doc de proyecto que la gente de verdad usa. En inglés.