Cada producto (del tipo que sea) debería ir acompañado por algún documento con instrucciones de su funcionamiento, o por el modo de aplicar el producto e inclusive, una descripción del contenido del producto. Y esto aplica aún para la documentación de software.

¿Leer las instrucciones?

Es verdad que un gran porcentaje de los clientes no lee las instrucciones, aún cuando una de las primeras frases es: “lea las instrucciones antes de usar el producto”. No se si esto sea solo en México, Latinoamérica o en todo el mundo, pero bueno, si cosas mas importantes como contratos no se leen la mayoría de las veces, qué podemos esperar de unos papeles que dicen como funciona un sencillo producto, “yo soy muy inteligente y puedo averiguar como funciona sin leer una sola palabra de las instrucciones“, es un pensamiento muy común al respecto. Y en ocasiones me da risa, al saber que aquellos que acostumbran no leer instrucciones, se quejan de que el producto no sirve, o se descompuso y no le hicieron válida la garantía, etc.

¿Quién gana o pierde más en este caso? ¿La empresa gana porque así el cliente tiene que gastar más dinero en refacciones o incluso un producto nuevo? ¿O tiene perdidas, porque ahora tiene un cliente menos, el cuál hace mala fama del producto haciendo que la gente no lo compre? ¿O simplemente el que pierde es el cliente por no leer las instrucciones?

Los desarrolladores se deben involucrar en la documentación

En el mundo del desarrollo de software tenemos la documentación del producto que algunas veces se encuentra en el menú de ayuda, pero parece sarcasmo, porque los que la hicieron eran los que la necesitaban, y esto se debe a que en muchas ocasiones las personas que lo hacen no son las mismas que desarrollaron el software, y a veces no tienen la menor idea de lo que puede hacer el programa, claro que también puede ocurrir lo contrario, en donde la documentación es muy buena, pero el funcionamiento del programa deja mucho que desear.

A muchos desarrolladores no les gusta documentar, sin embargo, deberían ser los principales involucrados en la elaboración de la misma, ¡nadie sabe mejor cómo funciona el programa! Además, puede servir como ejercicio para encontrar nuevas mejoras y bugs del mismo.

Creo que si los desarrolladores no escriben la documentación del producto, al menos uno de ellos debería de revisar junto con la(s) persona(s) que la hicieron para asegurarse que esté bien hecha, sobre todo cuando esta se escribe en un lenguaje y se traduce a otro. De esta forma también se añade calidad al producto.

Documentación en el código

Además de la documentación del producto que es la que el cliente final “lee” (o al menos la toca para guardarla, en el mejor de los casos) también existe la documentación interna del mismo, que es utilizada por la compañía durante el proceso de fabricación o desarrollo del producto.

En lo que al software respecta esto no es más que la documentación del código, la cuál puede constar de diagramas (UML por ejemplo) y comentarios en el código, gracias a los cuáles (hablando teóricamente por supuesto) cualquier desarrollador que se integre al proyecto podrá sin problema alguno leer los mismos y entender a la perfección la estructura del código para así poder corregir y/o agregar nuevas características al mismo. El día que esto pase, la selección Mexicana ganará el mundial de futbol, bueno, espero que se entienda que tan difícil creo que es. He trabajado en 5 compañías diferentes, y en ninguna existe algún proceso o método para escribir documentación de código.

Si no mal recuerdo la teoría de la Ingeniería de Software, 2/3 partes del desarrollo del producto debería estar enfocada al análisis del mismo, el cuál incluye los diagramas del mismo con los cuales, el programar sería una tarea más sencilla y ocuparía 1/3 del tiempo junto con las pruebas del mismo. ¡Oh triste y cruda realidad! Nos devanamos los sesos escribiendo miles de líneas de código primero y luego las pruebas nos dirán si lo que hicimos está bien o no.

“Ah, por cierto, no se necesita documentar el código, es muy fácil de entender, solo puse mi nombre y  fecha de creación por si necesitan que les explique algo, además, no pienso cambiarme de trabajo próximamente”.

La semana siguiente que esta persona deja la empresa, los que se quedan en la empresa y también con el código, tratan de descifrar para qué sirven las variables s1, s2, s3, s4, x, y, z, los métodos funcion1, funcion2, funcion3, etc; además que descubren que no puso su nombre en los comentarios, sino como se hacía llamar el mismo: “mrknowitall”.

A final de cuentas un software mal documentado termina siendo un software que puede tener muchas deficiencias en su funcionamiento, y se convierte en una pesadilla mantenerlo. Por lo que me vienen a la mente varias preguntas del por qué de esta situación, ¿acaso es que la demanda es mayor a la cantidad de programadores existentes que podemos darnos el lujo de no hacer las cosas bien?

Según este video, dentro de 10 años la demanda será de 1 millón 400 mil programadores (en  Estados Unidos), y solo habrá 400, 000 graduados.

¿Cuál es el valor que se le da a la documentación?

¿Será que la documentación del código no es considerada en el valor del producto, por lo tanto no vale? ¿Es problema por la mala administración en los proyectos? ¿Simple decidía de los programadores?

Qué pasaría si mejorara la documentación de código en el software. ¿Habría paz en el mundo? ¿Habría mejores sueldos para los programadores? ¿Tendríamos menos cantidad de programas qué hacen lo mismo, pero esos pocos serían de mucho mejor calidad? ¿Bill Gates no sería tan rico? ¿Más gente leería el manual de usuario de cada programa que compra? ¿No cambiaría nada?

¿Llegaste a esta pregunta sin siquiera sentirte mal por todas aquellas líneas de código que no comentaste?

Con todo esto no espero que el mundo cambie y mañana todo código sea comentado y entendido a la perfección, sino únicamente que se tome conciencia que desarrollar un software no es solo escribir código.