Un ingeniero nuevo cuesta 15.000 $/mes mientras se adapta. La documentación reduce eso a la mitad.

Un nuevo ingeniero cuesta la totalidad de su salario desde el primer día, mientras que genera un rendimiento cercano a cero durante su periodo de adaptación. Con un salario de ingeniero senior en EE. UU. de $180,000-$220,000, el coste mensual con cargas sociales incluidas es de aproximadamente $15,000-$18,000. Durante las semanas en que ese ingeniero está leyendo código, haciendo preguntas, asistiendo a sesiones informativas y, en general, absorbiendo el contexto en lugar de entregar código, la empresa está pagando el precio completo por una fracción del rendimiento.

Esto es completamente normal y esperado. La pregunta no es si existe un periodo de adaptación, sino cuánto dura, y el factor de influencia individual más importante en la duración de la adaptación es la calidad de la documentación a la que tiene acceso la nueva incorporación.

La diferencia de la documentación

En un equipo con documentación exhaustiva y actualizada, la primera semana de un nuevo ingeniero es así: leer la descripción general de la arquitectura, comprender los sistemas clave y cómo interactúan, revisar el registro de decisiones para las elecciones técnicas más importantes, seguir la guía de configuración y desplegar un pequeño cambio. Tienen preguntas, pero muchas de ellas son respondidas por los documentos, y las preguntas que quedan son específicas y enfocadas en lugar de generales y contextuales.

En un equipo sin documentación, la primera semana del mismo ingeniero se ve diferente: buscar a alguien dispuesto a explicarle el sistema, absorber lo que pueda de una descripción verbal que es necesariamente incompleta, tropezar en un proceso de configuración que está parcialmente documentado y parcialmente basado en preguntar a otros, y pasar un tiempo considerable tratando de entender no solo el sistema, sino a quién preguntar sobre cada parte del mismo.

La diferencia en el tiempo de adaptación suele ser de cuatro a seis semanas para equipos bien documentados, frente a ocho a doce semanas para los mal documentados. Con un coste de $15,000-$18,000 al mes, reducir el periodo de adaptación de diez semanas a cuatro semanas ahorra entre $22,500 y $27,000 por contratación.

Con diez contrataciones de ingenieros al año, lo cual es habitual para una startup en crecimiento, eso representa entre $225,000 y $270,000 de productividad recuperada. Para organizaciones más grandes que contratan veinte o más ingenieros al año, los ahorros aumentan de forma proporcional.

Qué contiene una buena documentación de incorporación

No toda la documentación ayuda por igual en la incorporación. Los documentos de incorporación que ofrecen un mayor impacto son:

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 proporciona a la nueva incorporación un modelo mental de todo el sistema antes de profundizar en cualquier componente individual.

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 la guía de configuración ahorra es un minuto que la nueva incorporación no pasa pidiendo ayuda a otra persona.

Decisiones clave y su justificación. Los registros de decisiones que explican por qué el sistema está construido de la forma en que lo está. Sin esto, la nueva incorporación cometerá errores repitiendo problemas ya resueltos o perderá tiempo debatiendo decisiones que ya han sido tomadas.

Convenciones del equipo. Estándares de codificación, expectativas de revisión de PR, procedimientos de despliegue, protocolos de respuesta ante incidentes. Las reglas no escritas que los miembros experimentados del equipo siguen inconscientemente y que las nuevas incorporaciones aprenden mediante prueba y error cuando no están documentadas.

Quién hace qué. Un mapa de las responsabilidades del equipo, la propiedad del sistema y a quién preguntar sobre áreas específicas. Esto por sí solo ahorra horas del tiempo de la nueva incorporación que, de lo contrario, pasaría tratando de entender la estructura del equipo mediante ensayo y error.

Documentación de incorporación que se escribe sola

La ironía de la documentación de incorporación es que suele crearse de forma reactiva, en las semanas anteriores o posteriores a la incorporación de un nuevo miembro, por parte de los ingenieros senior que ya son los que están más saturados de trabajo. La documentación se crea bajo presión de tiempo y, debido a que se crea para una contratación específica, a menudo no se mantiene una vez que esa persona ya no la necesita.

La documentación autogenerada cambia la situación económica al generar materiales de incorporación de manera continua a partir de la actividad diaria del equipo. La documentación de la arquitectura se mantiene actualizada porque se genera a partir de las PR y de las discusiones de diseño. Los registros de decisiones se capturan a medida que se toman las decisiones. La documentación de convenciones refleja la práctica real en lugar de directrices teóricas.

Cuando se une la siguiente contratación, los materiales de incorporación ya existen y están actualizados. Sin esfuerzos puntuales de documentación de última hora, sin apartar a los ingenieros senior de sus propios proyectos y sin páginas de wiki apresuradas que quedarán desactualizadas para el próximo trimestre.

Preguntas frecuentes

¿Cómo medimos el ROI de tener una mejor documentación de incorporación? Registre el tiempo transcurrido hasta la primera PR significativa (o el primer despliegue en producción) para las nuevas incorporaciones antes y después de mejorar la documentación. Esta es la medida más directa del tiempo de adaptación. También realice un seguimiento del número de preguntas que hacen las nuevas incorporaciones en su primer mes, que tiende a disminuir significativamente cuando se dispone de buena documentación.

¿Cuál es el documento de incorporación más importante que se debe crear primero? La descripción general de la arquitectura del sistema y la guía de inicio rápido. Juntos, abordan las necesidades más inmediatas de la nueva incorporación: comprender qué hace el sistema y ponerlo en funcionamiento localmente.

¿Se aplica esto a contratistas y profesionales independientes? Aún más, porque los contratistas suelen tener colaboraciones más cortas y menor tolerancia a periodos largos de adaptación. Una buena documentación permite que un contratista sea productivo en días en lugar de semanas, lo que significa que la organización obtiene más valor de la colaboración.

Lectura recomendada: El factor autobús, El coste oculto del conocimiento tribal, Deuda de documentación. Páginas relacionadas: Documentación autogenerada, Incorporación, Para equipos de ingeniería.