Por qué a los ingenieros les disgusta escribir documentación (y por qué tienen razón)

Si alguna vez has intentado que un equipo de ingeniería escriba más documentación, ya sabes cómo funciona. Hay un breve período de cumplimiento después del mandato, se crean o actualizan algunas páginas de la wiki y, en un mes, el equipo vuelve a su línea de base anterior. La iniciativa de documentación se une a la colección de procesos bien intencionados que no llegaron a consolidarse.

La interpretación estándar de la dirección es que los ingenieros son perezosos con la documentación o no entienden su importancia. Esta interpretación es errónea, y construir políticas sobre ella produce iniciativas que fallan repetidamente por las mismas razones estructurales.

Los ingenieros se resisten a la documentación porque sus objeciones son correctas.

Las verdaderas objeciones

El cambio de contexto es costoso. Escribir prosa y escribir código utilizan modos cognitivos diferentes. Cambiar del pensamiento lógico y estricto requerido para la depuración o la arquitectura al pensamiento explicativo y orientado al público requerido para la documentación es agotador de una manera que no se refleja en las hojas de horas. La mayoría de los ingenieros afirman que el cambio de contexto cuesta más que la propia escritura: los veinte minutos para volver al código después de pasar treinta minutos en una página de la wiki.

Se siente como algo de bajo estatus. En la mayoría de las culturas de ingeniería, entregar código es de alto estatus y escribir sobre código no lo es. Nadie es promocionado por sus contribuciones a la wiki. La evaluación de desempeño de nadie destaca la calidad de sus documentos de arquitectura. La estructura de incentivos dice a los ingenieros que la documentación es secundaria frente a la construcción, y ellos responden racionalmente a los incentivos.

Saben que quedará desactualizada en semanas. Esta es la objeción que la mayoría de los gerentes descartan y que la mayoría de los ingenieros sienten con más fuerza. Un ingeniero que ha visto cómo su documento de arquitectura cuidadosamente redactado pierde precisión después de unos pocos sprints de cambios aprende que el esfuerzo de escribir documentos tiene una vida útil muy corta. La respuesta racional es invertir menos esfuerzo en algo que se deteriora rápidamente, no más.

El público objetivo no está claro. ¿Para quién son estos documentos? ¿Futuros ingenieros? ¿Compañeros de equipo actuales que ya conocen el sistema? ¿Gerentes de producto? Según el público, el nivel de detalle adecuado, el enfoque y la profundidad técnica son completamente diferentes. Sin claridad sobre el público, el ingeniero escribe en el nivel incorrecto o no escribe nada porque la ambigüedad hace que la tarea parezca ilimitada.

Por qué la motivación no es la solución

Saber que estas objeciones son estructurales en lugar de motivacionales cambia la perspectiva de cómo debe ser la solución.

Los enfoques motivacionales (mandar documentos, añadir la documentación a los requisitos del sprint, gamificar las contribuciones) producen un cumplimiento temporal pero no abordan las razones subyacentes por las que los ingenieros se resisten. El cambio de contexto sigue siendo costoso, la jerarquía de estatus no cambia y los documentos siguen quedando obsoletos.

Los enfoques que realmente funcionan abordan la estructura en lugar de la motivación.

Eliminar a los ingenieros del ciclo de escritura. La documentación auto-redactada genera documentos estructurados a partir de la actividad de ingeniería que ya está ocurriendo: descripciones de PR y mensajes de commit, conversaciones de Slack donde se discuten decisiones, reuniones donde se debate la arquitectura. La contribución del ingeniero es el trabajo en sí, y la documentación es un subproducto en lugar de una tarea adicional.

Hacer que los documentos se mantengan actualizados automáticamente. Cuando la documentación se actualiza por sí misma a medida que cambian el código y las conversaciones subyacentes, la objeción de la obsolescencia desaparece. Los ingenieros están dispuestos a revisar y perfeccionar documentos en los que confían que son mayoritariamente precisos. No están dispuestos a escribir documentos que saben que estarán mal en un mes.

Clarificar el público a través del formato. En lugar de pedir a los ingenieros que escriban para un público indefinido, proporcione formatos estructurados: registros de decisiones para decisiones de arquitectura, documentos de incorporación para nuevas contrataciones, wikis de ingeniería para documentación del sistema. Cada formato implica su público, lo que hace que la tarea de escribir (o revisar) sea delimitada en lugar de abierta.

El modelo de revisión

El modelo de documentación más sostenible trata a los ingenieros como revisores en lugar de autores. El sistema genera la documentación inicial a partir de las fuentes disponibles (actividad de código, conversaciones, reuniones). El ingeniero revisa, corrige y enriquece. La revisión es una tarea de diez minutos en lugar de una sesión de escritura de dos horas, el cambio de contexto es mínimo y la contribución del ingeniero es el control de calidad sobre algo que ya existe en lugar de la creación desde cero.

Este modelo respeta el tiempo de los ingenieros, aborda sus objeciones y produce documentos que se mantienen actualizados. También tiende a producir mejor documentación que la escritura manual, porque los documentos generados son exhaustivos (capturan todo lo que sucedió en lugar de lo que el ingeniero recordó escribir) y consistentes (siguen un formato estándar en lugar de variar según el autor).

Preguntas frecuentes

¿Qué pasa con los ingenieros a los que realmente les gusta escribir documentación? Existen y son valiosos. En el modelo de revisión, se convierten en las personas que enriquecen y mejoran los documentos generados, aportando los matices, el contexto y la narrativa que los sistemas automatizados no pueden producir. Sus habilidades se aprovechan mejor en el enriquecimiento que en la escritura básica de la que se encarga el sistema.

¿Confiarán los ingenieros en los documentos generados por IA? Con más facilidad de la que se podría esperar, porque los documentos se generan a partir de fuentes que el ingeniero reconoce: sus propias PR, sus propios hilos de Slack, sus propias discusiones en reuniones. Los documentos citan estas fuentes, por lo que el ingeniero puede verificar cualquier afirmación consultando el original. La confianza se basa en la transparencia, y la generación respaldada por citas la proporciona.

¿Cómo manejamos la información clasificada o sensible? El sistema debe tener límites configurables para lo que captura. Se pueden excluir ciertos canales de Slack, ciertos repositorios o ciertas categorías de reuniones. El ingeniero controla lo que ve el sistema, lo que significa que la información confidencial queda fuera de los documentos generados.

Lecturas relacionadas: El coste de escribir documentos de ingeniería, La paradoja de la documentación, Explicación de los documentos auto-redactados. Páginas relacionadas: Documentos auto-redactados, Para equipos de ingeniería.