Documentación de incorporación: el camino desde una máquina nueva hasta un cambio fusionado

Objetivo

Que una persona recién incorporada llegue a su primer cambio fusionado siguiendo solo la documentación, y que esta mejore con cada nueva incorporación en lugar de degradarse entre una llegada y otra.

Requisitos previos

Un README que responda las preguntas básicas; un conjunto de primeras tareas pequeñas y etiquetadas; un responsable designado para el camino de incorporación. El capítulo citado de Google sostiene que la mayoría de los proyectos merecen un documento «Hello World» que no dé nada por supuesto y consiga que la persona ingeniera logre que ocurra algo real, y que el mejor momento para escribir ese tutorial es justo al incorporarse a un equipo. Diátaxis (citado) clasifica este documento como un tutorial: orientado al aprendizaje, una actividad práctica hacia un objetivo alcanzable.

Pasos

1. Escribir el camino como una única secuencia numerada, con el estado final indicado al principio: «al terminar habrás abierto, revisado y fusionado un cambio». Todo lo que no forme parte de ese camino va en otro sitio y se enlaza.
2. Dar cada paso de configuración como un comando exacto con su salida esperada, y una comprobación que la persona nueva pueda ejecutar («la batería de pruebas informa N superadas»). Los requisitos previos (cuentas, permisos, hardware) se listan antes del primer paso, no se descubren a mitad de camino.
3. Ofrecer una página de mapa con enlaces únicamente: repositorios, entornos, quién es responsable de qué, el glosario, los canales de comunicación, el calendario de versiones. Sin prosa que vaya a quedar obsoleta.
4. Señalar el conjunto de primeras tareas y la etiqueta que marca las tareas como adecuadas; el documento indica cómo reclamar una y qué significa «terminada» en este contexto.
5. Exigir que la persona nueva mantenga un registro de cada tropiezo, pregunta y solución improvisada durante los primeros días, y que convierta ese registro en pull requests contra los documentos de incorporación como sus primeras contribuciones.
6. Poner un responsable y una fecha de última verificación en el camino; volver a recorrerlo desde una máquina limpia cuando llegue alguien nuevo o a un intervalo fijo, y eliminar los pasos que ya no apliquen. El capítulo citado describe fechas de vigencia y marcar los documentos obsoletos en lugar de dejarlos como están.
7. Mantener una variante para agentes del mismo camino: comandos no interactivos, sin pasos que requieran un inicio de sesión en navegador donde se pueda proporcionar un token, y una lista explícita de acciones que el agente no debe realizar (desplegar, eliminar, contactar a personas).

Resultado esperado

El tiempo desde la llegada hasta el primer cambio fusionado queda acotado por el camino, no por la disponibilidad de un colega; los documentos de incorporación son las páginas que más a menudo se corrigen en el repositorio.

Límites y base de verificación

El camino cubre la mecánica, no el criterio; comprender el dominio sigue viniendo de trabajar con las personas y de los documentos de diseño. Los entornos que no se pueden reproducir en una máquina limpia (herramientas con licencia, datos restringidos) necesitan una alternativa declarada. No se afirma ninguna medición del tiempo de incorporación.