Documentación el gran problema

No es que la documentación sea un problema, es la falta de la misma o su mala orientación lo que produce cada día muchas ineficiencias y problemas que podrían haber sido fácilmente evitados.

El Problema

Por principio podríamos argumentar que una aplicación insuficientemente documentada pierde una gran parte de su valor aunque su funcionamiento sea correcto.

Cuando la única documentación existente en una aplicación es el código, será casi imposible de mantener y tendrá un alto peligro de producir errores no esperados y de quedar obsoleta en muy poco tiempo.

Cualquier modificación necesaria en la aplicación implicará:

• Revisar todo el código escrito.
• Perder el tiempo intentando comprender el funcionamiento.
• Dudar incluso de nuestro propio código.
• Volver a cometer los mismos errores.
• Perder calidad del código por incremento innecesario de parches.

Revisar todo el código

Aunque podríamos centrarnos en el punto concreto de la aplicación donde se encuentra el problema, la falta de documentación implica la necesidad de revisar el código completo para evitar sorpresas o efectos colaterales. En el caso de no proceder de esta forma, lo habitual es corregir un error y producir otros no esperados.

Perder el tiempo intentando comprender

Lo que un día fue sencillo de programar, quizás hoy nos parezca oscuro o tal vez ahora tengamos más experiencia. En definitiva, aunque seamos los autores del código a modificar hemos cambiado y necesitamos volver a comprender los motivos y decisiones implícitas en nuestro código. Este esfuerzo evidentemente representa una perdida de tiempo que podría haberse evitado con la documentación mínima necesaria.

El cambio continuo simplemente sería un motivo por el cual tenemos que documentar.

Dudar del código

Seguidamente comenzamos a dudar de las líneas de código que estamos analizando. Nuestro flujo de razonamiento es diferente al del programador que diseño la aplicación. Por suerte la programación no es una ciencia exacta y un mismo problema puede tener diferentes algoritmos que proporcionen una solución. Así pues, entramos en un proceso delicado en el cual intentamos corregir nuestra aplicación evitando alterar el funcionamiento general de la misma.

Volver a cometer los mismos errores

Cuando no existe documentación existe una alta probabilidad de volver a cometer errores del pasado y que quedan ocultos u olvidados entre las líneas de código.

Incremento de los parches en el código

Existe una frase popular entre los programadores “Si funciona no lo toques”

Se trata de la típica frase que se pronuncia cuando nos encontramos frente a un código que no tenemos nada claro, pero que curiosamente funciona o realiza la tarea que tiene asignada. Esta frase produce generalmente un incremento de los parches a introducir en el código que finalmente quedara con trozos de código nada claros pero que funcionan.

Es decir, la falta de documentación convierte a nuestras aplicaciones en zombis que esperan su oportunidad para saltar a la yugular de nuestra productividad. Creo que queda clara la necesidad de tomarnos muy en serio el tema de la documentación.

Pero, ¿Qué funciones tiene que cumplir la documentación?

Funciones

La documentación tiene que dar respuesta a muchos y diferentes requerimientos pero me gustaría remarcar los que considero principales y que son los siguientes:

• Objetivo.
• Apariencia estética y usabilidad.
• Estabilidad y mantenibilidad.

Objetivo

Es necesario que la documentación nos especifique claramente cual es el objetivo de la aplicación, cual es el problema que soluciona y cuales son las condiciones de aceptación de la misma.

Usabilidad

La documentación deberá ser clara y contener todas las guías de usabilidad necesarias tanto para los técnicos que posteriormente necesiten realizar el mantenimiento de la misma, como para los usuarios finales de la aplicación.

Mantenibilidad

Se trata de la parte más importante de la documentación y será la que posteriormente nos permitirá realizar un mantenimiento correcto y con la calidad necesaria. Evitando la obsolescencia del software y los errores colaterales por falta de información.

 

Una vez definidas las funciones principales, será necesario seguir una serie de reglas que nos faciliten la generación de la documentación y que nos permitan generarla de la forma más solvente posible.

Reglas

Las reglas básicas que tendrá que cumplir nuestra documentación serán las siguientes:

• Pensar en el destinatario del documento: Tendremos que adaptar el contenido de la documentación a quien la tenga que utilizar. Usuarios finales, equipo de mantenimiento, etc.
• No existen las trivialidades: Tenemos que documentar TODO lo necesario. Ni más ni menos. Si es demasiado extenso nadie lo leerá, si es demasiado escueto no será útil. Además, no debemos ahorrar las claves importantes por triviales que nos parezcan.
• Escribir de forma sencilla: Cuanto más sencillo sea el vocabulario y las frases sean más cortas y fáciles de entender todo mucho mejor.
• Incluir imágenes y explicaciones gráficas: Si lo podemos explicar con un diagrama o una imagen podremos disponer de una documentación mucho más directa y útil.
• Estructurar el contenido: Los usuarios de la era internet estamos acostumbrados a escanear visualmente los documentos por lo que la estructura del documento es esencial para su efectividad posterior.

En resumen

Existe un grave problema con la falta de documentación. Documentación que es necesaria y que tiene que cubrir un conjunto de funciones esenciales entre las cuales destaca la mantenibilidad del software.

Finalmente, para conseguir una documentación útil y de calidad hemos de seguir un conjunto de reglas encaminadas a facilitar la labor del destinatario de la misma.