Mapas, oro y especias: por qué descuidar la documentación puede hacer naufragar su proyecto

¿Cuál era el bien más valioso que los antiguos exploradores traían de sus viajes? ¿Oro y especias? No. Los mapas.

Cristóbal Colón nunca habría realizado su famoso viaje en 1492 sin un mapa Diseñado por sus predecesores, un juego de espionaje para obtener mapas portugueses sentó las bases de la Compañía Holandesa de las Indias Orientales, posiblemente la empresa más cara de la historia de la humanidad. En su apogeo en 1637, valía 78 millones de florines holandeses, el equivalente a 7,9 billones de dólares en dólares de 2017. Eso supone más de 10 billones de dólares en dinero de 2024, más que Microsoft , Nvidia y Apple. conjunto Los tesoros palpables provenientes de nuevas tierras eran importantes en el corto plazo, pero desde una perspectiva más amplia, era el conocimiento el que forjaba verdaderas fortunas.

¿Por qué, en el mundo tecnológico actual, solemos olvidarnos de esto? En la búsqueda del éxito inmediato, a menudo nos mostramos reacios a dedicar tiempo y recursos valiosos a la producción y el mantenimiento de documentación técnica. Hablando en términos del siglo XVII, nos apresuramos a conseguir oro y especias sin trazar nuestros mapas, lo que, a su vez, podría habernos llevado a conseguir mucho más oro y especias. ¿Eres escéptico? Ahoy, veámoslo más de cerca...

Código loco

“Como seguramente recordará, la estasis hipnoide de los patrones neuronales del cerebro puede ser escaneada por un haz extra-electromagnético que…” “¡Deje de hablar!”, dijo Ard Vark con impaciencia. “¿Qué quiere decir con “como seguramente recordamos?” ¿Cómo podemos recordarlo si nunca lo supimos? Esta cita de Wacky World, una historia del gran escritor de ciencia ficción Edmond Hamilton, se refiere a los marcianos, no a los programadores. Sin embargo, muchas personas ven a los desarrolladores como si fueran de otro planeta, especialmente aquellos que solo tienen una vaga idea del desarrollo de software y sus complejidades. El hecho es que los desarrolladores a menudo asumen que otros conocen el código tan bien como ellos y con frecuencia consideran innecesaria la documentación técnica. Esta mentalidad corre el riesgo de hacer que el proyecto sea tan complejo e incomprensible para los externos como una “estasis hipnoide”, lo que en última instancia pone en peligro el éxito potencial del proyecto.

La reticencia a crear documentación suele deberse a las mismas razones por las que la gente pospone las cosas en otras áreas: requiere una inversión de tiempo y dinero considerables. En otras palabras, suele deberse a la pura pereza y al deseo de ahorrar dinero, que no son obstáculos fáciles de superar. Sin embargo, la documentación no es solo información redundante que supuestamente es obvia para todos; contiene detalles críticos que pueden ser indispensables. A menudo, la ausencia de documentación complica significativamente la detección y corrección de errores, dificulta el mantenimiento y las actualizaciones y aumenta el tiempo necesario para incorporar a nuevos miembros al equipo. Mientras que los equipos sin documentación se ven obligados a realizar tareas repetitivas, los proyectos con documentación bien estructurada muestran una alta eficiencia y confiabilidad; esto es un hecho, no una mera opinión.

Sí, algunos programadores afirman que el código que escriben es tan claro y comprensible que la documentación es simplemente innecesaria. Sin embargo, en realidad, incluso el código más perfecto puede resultar confuso para otros o perder su claridad con el tiempo. Lo que parece claro hoy puede convertirse en un rompecabezas mañana. Por ejemplo, ¿podrías manejar fácilmente una simple tarjeta perforada de los años 70?

Factor bus, Burnout y otras bestias fantásticas

La teoría es buena, pero la práctica es más convincente. A continuación se presentan algunos ejemplos basados en historias reales, en los que solo se citan nombres de personas y empresas ficticios. Estos breves estudios de casos cubren los problemas más típicos que surgen debido a prácticas deficientes de documentación técnica.

Historia n.° 1: Incapacidad para escalar

El proyecto "NoDocumentationPlease", que en un principio era una startup de streaming de vídeo de éxito, se enfrentó a graves problemas a la hora de intentar escalar debido a la escasa documentación técnica. Cuando el equipo tuvo que ampliar su equipo, los nuevos empleados no comprendían plenamente sus tareas y nadie podía ofrecerles una explicación adecuada. Sin el apoyo y la formación adecuados, los nuevos empleados se marchaban rápidamente. Esto no solo ralentizó el progreso del proyecto, sino que también provocó la pérdida de talentos clave, lo que en última instancia puso en peligro la eficacia general y el futuro del proyecto. Como resultado, los streamers abandonaron el chat y el proyecto se cerró.

Historia n.° 2: Problemas de mantenimiento

La empresa "IKnowEverything" desarrolló una plataforma en la nube para la sincronización y el almacenamiento de datos. Al principio, el proyecto avanzó rápidamente, pero con el tiempo, sus desarrolladores se enfrentaron a dificultades para mantener y actualizar la plataforma debido a la falta de documentación técnica clara y actualizada. Esto provocó un desarrollo más lento, más errores y clientes insatisfechos. Con el tiempo, la empresa comenzó a perder a sus antiguos clientes y los nuevos clientes optaron por competidores con soluciones más estables y fiables. Los ingresos disminuyeron significativamente mientras que el coste del mantenimiento ineficaz aumentó. La documentación adecuada de los aspectos técnicos desde el principio podría haberles permitido escalar con éxito. Sin embargo, no se hizo a tiempo. En consecuencia, la empresa no pudo superar los desafíos técnicos y financieros y cerró.

Historia n.° 3: Agotamiento del desarrollador

El proyecto "SmartestEver" enfrentó graves problemas porque su desarrollador principal, Andrew, que se encargaba de casi todo, renunció después de verse abrumado por las numerosas preguntas del equipo. Si "SmartestEver" hubiera tenido la documentación adecuada, los desarrolladores junior podrían haber consultado fácilmente las preguntas frecuentes y resuelto los problemas rutinarios. En cambio, bombardearon a Andrew con preguntas y, sin él y la documentación necesaria, el equipo simplemente no pudo continuar y el proyecto se cerró (presione F para Andrew).

Historia #4: El factor autobús

En la empresa "NoDocsNeeded", John, un desarrollador clave, estaba desarrollando un prometedor producto de software. Tenía todo el conocimiento pero no se molestó en documentarlo. Sus gerentes tampoco se molestaron en convencerlo. Llegó un día en que John se fue de viaje de negocios y simplemente no regresó. Sin documentación ni comprensión de la arquitectura y la lógica del producto, los miembros restantes del equipo básicamente no podían hacer nada. El proyecto se paralizó y el dinero invertido en él se desperdició. La lección es simple: la documentación y la distribución del conocimiento dentro de un equipo son cruciales para evitar la dependencia de una sola persona. Por cierto, todavía están buscando a John...

Historia #5: Ningún profeta es bienvenido en el código abierto

María creó su primera biblioteca de código abierto, pero no escribió ninguna documentación para ella. Nadie entendía lo que hacía la biblioteca, y María decidió que no escribiría más bibliotecas porque le parecía inútil. El proyecto de María terminó antes de empezar y ella decidió cambiar de profesión.

De grumete a capitán

Bien, ya tenemos algo de teoría y práctica, ahora vamos a sumergirnos en la investigación y las estadísticas. Encuesta para desarrolladores de Stack Overflow 2024 Estados El 84% de los encuestados utiliza documentación técnica para comprender la funcionalidad de las tecnologías. Sin embargo, incluso con documentación, a menudo no pueden encontrar las respuestas que necesitan, como lo demuestran los siguientes recursos más populares: Stack Overflow (80%), tutoriales escritos (68%), blogs (61%) y videos instructivos (54%). Microsoft Research: La vida diaria de los desarrolladores de software encontró que, en promedio, los desarrolladores dedican entre el 1 y el 2 % de su día (8 a 10 minutos) a la documentación, y el 10,3 % de los desarrolladores afirman que la documentación obsoleta los obliga a dedicar demasiado tiempo a buscar respuestas por su cuenta. La necesidad de documentación también es una preocupación importante para la comunidad académica. Una simple búsqueda en Google Scholar de <"documentation" AND "software"> rendimientos más de 4 millones de resultados, lo que indica claramente una gran cantidad de publicaciones científicas que abordan el tema.

Las principales conclusiones son sorprendentemente simples: 1. Todo el mundo necesita documentación para entender la tecnología y/o el trabajo de otras personas; 2. Pocas personas se molestan en escribirla y mantenerla; y, en consecuencia, 3. Mucha documentación está mal escrita, desactualizada y, en general, inútil. Entonces, ¿qué hay que hacer? Cambiar la motivación en todos los niveles.

Un grupo de investigadores de la Universidad de Ciencias Aplicadas HAN y de la Universidad de Groningen (ambas en los Países Bajos) identificado Los problemas más típicos con la documentación técnica:

• La documentación informal que suelen utilizar los desarrolladores es difícil de entender;

• La documentación se considera un desperdicio cuando no contribuye inmediatamente al producto final;

• La productividad de un desarrollador se mide únicamente por la cantidad de software en funcionamiento;

• La documentación a menudo no está sincronizada con el software real;

• Los desarrolladores a menudo se centran únicamente en el corto plazo, especialmente en entornos de desarrollo de software continuo.

  
  

¿Le suena familiar algo de esto? Apuesto a que la mayoría de nosotros nos hemos topado con la mayoría o incluso con todos ellos a la vez en nuestro trabajo diario. Y hay más que la simple postergación o falta de recursos. Algunos de estos problemas provienen de una falta de gestión adecuada, planificación a largo plazo y, en última instancia, de visión estratégica. Y aquí viene la parte difícil, porque no depende solo de nosotros, los desarrolladores, resolverlos. Algunos problemas deberían ser abordados por gerentes, partes interesadas del producto o incluso propietarios de la empresa. Por eso es crucial que las opiniones adecuadas sobre cuestiones técnicas no sean solo un bonito accesorio, sino que formen parte de los valores fundamentales de toda la empresa, compartidos por todos, desde los fundadores hasta los desarrolladores junior.