Cómo reducir la incorporación de ingenieros de meses a días

La experiencia típica de incorporación (onboarding) de un ingeniero en una empresa en crecimiento es algo así. Semana uno: configuras tu entorno de desarrollo utilizando una guía parcialmente desactualizada. Pasas dos horas tratando de entender por qué se omitió un paso debido a un cambio en una dependencia. Preguntas en Slack. Esperas a que alguien responda. Semana dos: acompañas a alguien del equipo que te explica la arquitectura de forma verbal mientras intentas tomar notas. Entiendes, con suerte, el 40%. Semana tres: te asignan la corrección de un pequeño error. Pasas la mayor parte de la semana entendiendo el código lo suficientemente bien como para encontrar el archivo correspondiente. Semana cuatro: finalmente envías tu primer PR. Lo revisan y descubres que has infringido tres convenciones que nadie te había mencionado.

A las seis u ocho semanas, empiezas a ser moderadamente productivo. A los tres meses, ya puedes trabajar de forma independiente en la mayoría de las tareas. El equipo asume este cronograma como normal porque es el mismo para cada nueva incorporación, lo que hace que parezca algo intrínseco al puesto en lugar de un síntoma de falta de documentación.

Es un síntoma de falta de documentación.

Qué reduce a la mitad el tiempo de incorporación

La investigación y la experiencia práctica apuntan sistemáticamente a la misma conclusión: el factor más determinante en la velocidad de incorporación de un ingeniero es la calidad y la exhaustividad de la documentación disponible para las nuevas incorporaciones. Los equipos con documentación completa y actualizada realizan la incorporación en tres o cuatro semanas. Los equipos que no la tienen tardan de ocho a doce.

La diferencia radica en las actividades a las que el nuevo empleado dedica su tiempo. En un equipo bien documentado, el recién llegado pasa su primera semana leyendo: la arquitectura del sistema, las decisiones clave y su justificación, las convenciones del equipo, la guía de inicio rápido. Tienen preguntas, pero estas son específicas y enfocadas, en lugar de amplias y contextuales. En un equipo sin documentación, el nuevo empleado pasa sus primeras semanas reconstruyendo este conocimiento a través de conversaciones, lo cual es más lento, menos completo y también consume el tiempo de otros ingenieros.

Los cinco documentos de incorporación que más importan

No toda la documentación ayuda de la misma manera en la incorporación. Estos cinco documentos son los que aportan mayor valor.

Descripción general de la arquitectura del sistema. Un mapa de los servicios principales, cómo se comunican y de qué es responsable cada uno. Esto le da al nuevo empleado un modelo mental de todo el sistema antes de sumergirse en cualquier componente. Sin él, pasan semanas construyendo este modelo mediante deducciones y preguntas, y el modelo que construyen suele ser incompleto o incorrecto.

Guía de inicio rápido. Instrucciones paso a paso para configurar el entorno de desarrollo, compilar el proyecto, ejecutar pruebas y desplegar un cambio. Cada minuto que ahorra esta guía es un minuto que el nuevo empleado no pasa pidiendo ayuda a otra persona. Pon a prueba esta guía haciendo que alguien que no sea ingeniero la siga. Si no consiguen poner en marcha el proyecto, la guía tiene lagunas.

Registros de decisiones. La justificación documentada de las decisiones técnicas clave. Por qué el servicio de autenticación es independiente del monolito. Por qué se eligió esa base de datos en particular. Por qué el flujo de datos utiliza procesamiento por lotes. Sin esto, el nuevo empleado cometerá errores que repetirán problemas ya resueltos o perderá el tiempo discutiendo decisiones que el equipo tomó hace meses.

Convenciones del equipo. Estándares de codificación, expectativas de revisión de PR, formato de los mensajes de commit, procedimientos de despliegue, protocolos de respuesta ante incidentes. Las reglas no escritas que los miembros experimentados del equipo siguen inconscientemente y que los nuevos empleados aprenden mediante ensayo y error cuando no están documentadas. ¿Esas tres convenciones que nadie le contó al nuevo empleado y que fueron señaladas en su primera revisión de PR? Deberían estar en este documento.

Quién es el dueño de qué. Un mapa de las responsabilidades del equipo, la propiedad de los sistemas y a quién preguntar sobre áreas específicas. Solo esto ahorra horas del problema de "¿quién sabe sobre X?" que afecta a los equipos en crecimiento.

Por qué los documentos de incorporación se quedan obsoletos (y cómo solucionarlo)

La ironía de la documentación de incorporación es que, por lo general, se crea de forma reactiva, en las semanas anteriores o posteriores a la llegada de un nuevo empleado, por parte de los ingenieros más experimentados, que ya son los más saturados de trabajo. La documentación se crea bajo presión, a menudo está incompleta y, como se creó para una contratación específica, rara vez se mantiene una vez que esa persona ya no la necesita. Para cuando se incorpora el siguiente empleado, los documentos están parcialmente obsoletos y el ciclo se repite.

La documentación que se escribe sola cambia esto al generar materiales de incorporación de forma continua a partir de la actividad diaria del equipo. La documentación de la arquitectura se mantiene actualizada porque se genera a partir de PRs y discusiones de diseño. Los registros de decisiones se capturan a medida que se toman decisiones en reuniones e hilos de Slack. La documentación de convenciones refleja la práctica real en lugar de directrices aspiracionales de hace seis meses.

Cuando se incorpora el siguiente empleado, los materiales de incorporación ya existen y están actualizados. Sin esfuerzos de última hora para documentar, sin apartar a los ingenieros experimentados de sus proyectos y sin páginas de wiki apresuradas que quedarán obsoletas en el próximo trimestre.

Medir la mejora

Si estás defendiendo la inversión en documentación de incorporación, estas son las métricas que importan.

Tiempo hasta el primer PR significativo. La medida más directa de la velocidad de adaptación. Realiza un seguimiento de esto para cada nueva incorporación antes y después de mejorar la documentación.

Preguntas realizadas en el primer mes. Cuenta los mensajes directos de Slack y las preguntas que se habrían respondido con la documentación. Una disminución significativa indica que los documentos están funcionando.

Tiempo de interrupción de los ingenieros sénior. Realiza un seguimiento de cuánto tiempo dedican los ingenieros sénior a responder las preguntas de los nuevos empleados antes y después de que existan los documentos. Esto mide el beneficio para el equipo existente, no solo para la nueva incorporación.

Confianza autoinformada. Pregunta semanalmente a los nuevos empleados qué tan seguros se sienten navegando por el código de forma independiente. La pendiente de esta curva mejora notablemente con una buena documentación.

Con un salario de ingeniero sénior de $180,000 a $220,000, reducir el tiempo de adaptación de diez semanas a cuatro semanas ahorra aproximadamente entre $22,000 y $27,000 por contratación. Con diez contrataciones al año, eso representa más de $200,000 en productividad recuperada, financiada enteramente por documentación que puede generarse automáticamente.

Preguntas frecuentes

¿Qué pasa si nuestro sistema es demasiado complejo para documentarlo? Si es demasiado complejo para documentar, es demasiado complejo para que los nuevos empleados lo aprendan de manera eficiente, lo que significa que la complejidad en sí misma es un cuello de botella para el crecimiento. La documentación obliga a tener claridad sobre qué es el sistema y cómo funciona, lo cual es valioso incluso si la documentación no es perfecta. Comienza con la descripción general de la arquitectura e itera.

¿Deberíamos asignar un compañero de incorporación (buddy) en su lugar? Ambas cosas. Un compañero proporciona la incorporación social y cultural que los documentos no pueden dar. Los documentos proporcionan la incorporación técnica y arquitectónica que un compañero no puede transmitir de manera exhaustiva en conversaciones. El tiempo del compañero se aprovecha mejor en criterios de decisión, presentaciones y contexto cultural que en explicar el proceso de despliegue.

¿Cómo mantenemos los documentos actualizados? La respuesta estructural es una documentación que se mantiene a sí misma a partir de la actividad de ingeniería en vivo. La respuesta manual es asignar un propietario a cada documento y revisarlo trimestralmente. La respuesta estructural es más confiable porque no depende de que nadie se acuerde de hacer la revisión.

Lecturas relacionadas: El coste real de la incorporación de ingenieros, Cómo escalar un equipo de ingeniería, Deuda de documentación. Páginas relacionadas: Documentación que se escribe sola, Solución de incorporación, Para equipos de ingeniería.