Software funcionando sobre documentación extensiva

3

Seguimos repasando ese documento que apenas llena una cara de un folio (el manifiesto) y vamos al segundo grupo de valores. En la anterior entrada repasamos el primer grupo: “Individuos e Interacciones sobre Procesos y Herramientas“. De esos 4 conceptos salió un artículo extenso. Y éste no será menos.

Working software over comprehensive documentation

En la primera entrada, “Individuos e interacciones sobre procesos y herramientas”,  repasamos los recursos del área de desarrollo (personas, procesos, herramientas) y dejamos claro que lo que más nos importa es las personas. Ahora vamos a la salida del proceso de desarrollo. Si me preguntan que dos salidas tiene un proceso de desarrollo, lo tengo claro: software y documentación. No es casualidad ir emparejando así los grupos de valores. Un primer valor empareja los recursos. Esta segunda línea repasa las salidas y deja clara cuál es la salida importante.

Y es que creo que esa es la misión principal de esta frase: dejar claro que nuestro objetivo es desarrollar software, y que éste funcione. Todo lo demás, es secundario.

Software funcionando por encima de todas las cosas

La palabra “funcionando” no es gratuita. Hacer algo que luego no se usa, no vale. Mientras el código no esté en producción, no vale. El código de “soporte”, como automatización, test automáticos, no vale. Lo importante de verdad es el software funcionando, el que proporciona utilidad. Cierto es que muchas de estas cosas proporcionan valor, pero no son lo más importante. Hacemos tests, para asegurar que nuestro software funcione. Hacemos automatización para poder tener software funcionando al menor coste.

Y lo cierto es que no importa lo ordenado, lo automatizado, o lo bien gestionado que esté el software, sino si funciona y si no tiene fallos.

Nuestros usuarios no van a usar el test. No van a ver el diagrama ER. No van a usar esa arquitectura de microservicios tan molona. Ni tampoco van a utilizar ese ciclo de depliegue basado en CI/CD. Van a usar la aplicación. Ese es el motivo por el que todavía tenemos aplicaciones legacy que son auténticos monstruos para mantener: porque en el fondo son software funcionando.

Con esto no quiero decir que todo lo que he citado no sea importante. Es importante porque nos permite tener software funcionando. Y nos lo permite en dos sentidos:

  • Porque podremos aportar más software funcionando.
  • Porque el software no se romperá, funcionará.

Lo importante es no perder el foco. Hacemos testing porque queremos software funcionando. Aplicamos una arquitectura de microservicios porque nos permitirá mantener más fácilmente el sofware funcionando y entregar antes a negocio el software funcionando.

No cambiamos la plataforma COBOL a una en Go, porque sí. No lo hacemos porque el Go es mejor. Si la plataforma COBOL funciona y no nos cuesta mantenerla, ¿Para qué cambiar? Si cambiamos es porque creemos que tendremos mas funcionalidad, a menor coste o con menos fallos; no porque sea más moderna.

Si no aporta no está funcionando

Software funcionado tiene truco. Usa gerundio (present participle, si miramos el original en inglés). Esta forma verbal indica que es una acción que está pasando. Está funcionado ahora. No es lo mismo que “software que funcione”. Eso indicaría una característica del software, no lo que está pasando ahora.

El matiz es importante, porque una funcionalidad, sin fallos, que nadie usa no es software funcionando. De nada sirve tener una aplicación perfecta si está apagada. Y de nada sirve tener una aplicación perfecta en producción si nadie la usa.

Así, software funcionando lleva implícito el valor del software. Si no aporta valor, no podemos decir que esté funcionando. O está funcionando menos.

Documentación extensiva, no

Como siempre, la derecha es un valor. La documentación, incluso si es extensiva es un valor. Pero no puede ir por delante del software funcionando. Si documentar implica tener menos software en marcha, entonces no documentamos.

Escribir mucha documentación tiene muchos contras entre los que destacaré:

  • Cuanto más extensa es la documentación, antes pierde el valor. Caduca antes.
  • Todo el tiempo dedicado a documentar es tiempo que no se programa.
  • Cuanto más extensa más difícil es encontrar lo que buscas, y normalmente buscas en otro sitio que no sea la documentación.

Hay mucha documentación que se genera en un desarrollo que nadie lee. Me refiero a que nadie lee nunca. Ya escribiré un artículo sobre eso porque tengo muchas anécdotas sobre documentación que nadie lee.

Esa documentación no aporta valor alguno, sólo coste.

Calculemos el coste de generar la documentación en horas. Ahora piensa en la veces que alguien va a tener que desarrollar algo y pide documentación y le dices que no hay. Piensa en la cantidad de horas que necesitará para descubrirlo preguntando a gente y repasando el código. Ni se acerarán. Las horas que ahorrarás en el futuro serán mucho menores que las que has invertido. Y nadie te asegura que en el ciclo de validez de la documentación alguien vaya a necesitarla.

Otro aspecto es que cuanto menos conoces de la aplicación, peor será la documentación. Así que la documentación en fases tempranas del desarrollo es la más inútil de todas. Y la peor de todas, los requisitos. Odio los requisitos documentados, los casos de prueba documentados y toda la documentación previa a echar una línea de código.

Un resumen en un business case para convencer de la inversión, tiene su función. Un requisito documentado hasta la médula, no. Lo importante es software funcionando, y para ello es necesario que el desarrollador entienda lo que quiere negocio. No es importante que quede escrito, es importante que se entienda. Si cuatro líneas en una servilleta bastan, ¿Para qué invertir más?

Documentación valiosa, sí

Lo que debe quedar claro es que en ningún momento se dice documentar no. Hay muchos casos en los que documentar sí aporta valor. Por ejemplo un manual de usuario. Un memo explicando la nueva funcionalidad. O un diagrama de la arquitectura. Son cosas que el ratio de tiempo que costará hacerlas, comparado con el número de veces que se leerán y ahorrará tiempo a los lectores, es muy superior a 1. Es decir, es documentación rentable.

Y como ya he dicho en “Técnicos demasiado exquisitos“, los programadores son muchas veces los mejor preparados para hacer esa documentación.

El riesgo principal de este valor es que parece que ha dado un escudo a los programadores con el que puede defenderse de la documentación. “Documentar no es ágil”. Pues siento deciros que estáis equivocados.

Volviendo a la raíz de la frase del manifiesto: Hacer una funcionalidad que nadie usa es software funcionando? Y si la usan mal? Documentar para permitir que los usuarios usen bien el programa es ayudar a conseguir software funcionando.

Documentar para permitir que nuevos desarrollos cueste menos hacerlos, es conseguir más software funcionando.

Al final es un tema de sentido común: ¿Qué valor aporto? ¿qué me cuesta?

Documentar por documentar, es tontería.

Documentar inteligentemente

Además hoy en día hay maneras de documentar que hace que cueste mucho menos y convierten a la documentación en mucho más útil. El código puede estar documentado y con un par de frases cubrir mucho más que un documento en una wiki. Hay sistemas que añadiendo un par de anotaciones te crean una suite documentada y plataforma de pruebas de una API con Swagger. Y lo mejor es que si tocas el código, ves la documentación asociada y no te olvidas de actualizarla. Así que la probabilidad de que siga viva aumenta.

En vez de hacer un manual, puedes grabar un video de la pantalla mientras se habla y hacer una demo grabada. O puedes dejar embebida la documentación en la propia aplicación. O puedes trabajar los mensajes de error de forma que guíen y enseñen al usuario como se usa, o le den sugerencias cuando vemos que algo que podría ser útil no se usa.

Documentar no tiene porque ser un word. Puede ser muchas cosas más.

Conclusiones

Nuestro objetivo final es tener software funcionando, lo que implica que este debe estar desplegado, sin fallos y siendo usado. Todo lo que hacemos es para conseguir eso. Todo lo demás, en especial la documentación, sólo aportará valor y deberemos hacerlo si colabora en tener software funcionando.

Sobre el autor

Jose M. Huerta

Jose es Gestor de TI en Mallorca. Es Ingeniero de Telecomunicaciones y obtuvo el Master of Advanced Studies durante su etapa como investigador. Pero no tardó en abandonar ese mundo y meterse de cabeza en el mundo de las Tecnologías de la Información. Está certificado como ITIL Expert. Tiene amplia experiencia en gestión de servicios, clásica e integrada con desarrollo, gestión de desarrollo de software, usando metodologías clásicas, o desarrollo ágil, gestión de programas y portfolios, gestión de grandes grupos de personas, localizadas y off-shore, sin dejar de perder de vista el lado técnico y freak del sector. Ha trabajado en varias empresas del sector con distintos roles en áreas tanto de gestión de servicios de soporte como de equipos de desarrollo. Actualmente trabaja en WebBeds, como responsable del equipo de operaciones TI.

3 comments

  1. Gonzalo 7 marzo, 2019 at 16:55 Responder

    Que buena entrada…
    Me quedo con lo de la documentacion!!!!
    Y esto
    “¿Para qué cambiar? Si cambiamos es porque creemos que tendremos mas funcionalidad, a menor coste o con menos fallos; no porque sea más moderna.”
    Es triste que asi deberia ser pero no en mi experiencia no lo es… Se cambia de lenguaje, plataforma, etc no porque nos ofrezca mejoras se cambia por moda, sino es inentendible que se programe en java…

Post a new comment