ES IMPORTANTE LA DOCUMENTACIN DE SOFTWARE?

Por Reena Raj

Todos los profesionales del rea y que estn detrs del diseo del producto se enfrentan a
esta pregunta. La actividad puede parecer redundante para ellos, ya que su enfoque
principal est en la codificacin. Y el equipo tcnico puede muy bien suponer que ya que
dicha informacin se almacena en la cabeza, tener la idea y el concepto sobre el papel no
es ms que un desperdicio de recursos.

Recuerdo este incidente, mientras trabajaba para una pequea de desarrollo. Desde que
la empresa se encontraba todava en la fase de despegue, sus procesos empresariales an
no estaban en su lugar. Sin embargo, con el paso del tiempo, la empresa comenz a crecer
en tamao y los proyectos estaban siendo implementados sin ninguna evidencia
documental que los soportara. Pronto, la compaa fue adquirida por otro gigante de la
industria, que tom las riendas de la gestin y ejecucin del proyecto.

La continuidad del proyecto plante un problema ya que la documentacin no estaba en
su lugar. A excepcin de los documentos de sntesis y una versin antigua de arquitectura
de software, ningunas otras directrices podan ser encontradas. No se haban
documentado los porqus y los cmo del cdigo. Del mismo modo, el documento de
diseo tcnico no se ha actualizado con los ltimos cambios. No hubo ninguna explicacin
de por qu una tecnologa especfica se implement o por qu se adopt una estrategia
particular. El flujo funcional faltaba.

El nuevo equipo, obviamente, tuvo un momento difcil tratando de armar las distintas
piezas del rompecabezas. La administracin se qued con dos opciones: desechar todo el
proyecto y empezar todo de nuevo, o modificar la funcionalidad para satisfacer las
necesidades actuales de la organizacin. Y ambas opciones conllevan limitaciones en
trminos de tiempo e inversin de recursos humanos.

Muchos de nosotros como desarrolladores de software podemos optar por ignorar el
hecho de que la documentacin del software es realmente importante. Pero antes de
justificar tal declaracin, veamos las categoras de documentacin del software y luego
ver su importancia en cada nivel.

La documentacin del software se puede clasificar en dos niveles - el nivel diseo
(sistema) y el nivel del usuario final.

Documentacin en el diseo e implementacin del sistema se conoce como la
documentacin del sistema. La documentacin a nivel de diseo incluyen los documentos
Manual Tcnico y manual Funcional.

Los documentos tcnicos dan una idea de lo que est sucediendo y permite al final de
desarrollo comprender la arquitectura y el cdigo que se debe implementar para lograrlo.
La documentacin del sistema es importante porque permite la mantenibilidad del
software. La documentacin del sistema ayuda al lector a comprender la lgica y la razn
detrs de la implementacin de una solucin particular y si es especfico para esa fase.
Evita que los programadores repitan esos errores (tales como la implementacin de una
clase o mtodo en particular) que fueron rechazados en el pasado debido a su inviabilidad
. Aos ms tarde, una documentacin existente sera una buena manera de mirar atrs y
evaluar las estrategias adoptadas y las soluciones implementadas y evitar posibles
dificultades en el futuro.

Adems, con tantos cambios en el desarrollo de software, un sistema de referencia en
forma de documentacin permite que el trabajo contine.

Aunque siempre ha habido un debate sobre si la documentacin del sistema debe ser
ntida, precisa y corta o completa y extensiva . No hay uso de la creacin de la mejor
documentacin de calidad si el diseo y la arquitectura es malo y la calidad del cdigo,
pobre.

La segunda categora de la documentacin es el utilizado por los clientes, los
administradores o los usuarios del producto. En este tipo de documentacin se
proporcionan instrucciones o informacin para el uso de un software. La Informacin
representa la cara del producto y es la primera cosa a la que un cliente est expuesto. Si
un software es fcil de usar, no habra ninguna necesidad de manuales de usuario o guas.
Sin embargo, ya que un producto rara vez es tan intuitivo, se hace imperativo explicar el
uso de esa funcionalidad no evidente.

Imagnese la situacin de los compradores que tienen que pasar por el calvario de
encontrar la manera de instalar o utilizar el software que compr sin directrices o
instrucciones adjuntas. Para el caso, considerar la compra de una impresora o un
electrodomstico o un nuevo telfono mvil sin un manual! Una persona comn se
perdera y no sabra por en dnde empezar.

Llegando a la parte de resolucin de problemas - Cmo puedo hacer esto? Cmo puedo
salir de este problema? Dnde puedo encontrar informacin sobre los problemas de
compatibilidad? Una vez desarrollado, el software no garantiza que trabajar sin errores a
pesar de todas las pruebas y un entorno operativo perfecto. Qu hace un usuario cuando
las cosas van mal o el software comienza a vomitar errores? Las soluciones a un posible
conjunto de problemas que podran encontrarse durante su uso se encapsulan en la gua
de solucin de problemas.

Si la documentacin del software es importante o no, tambin se rige por el factor de
costo. Lo que mucha gente tiene en mente es el alto costo de produccin de esa
documentacin y, por lo tanto, tienden a descartar la idea de inmediato. Para otros, es
slo una parte de la informacin adicional que la gente puede o no puede preferir leer.
Otros apuestan por la facilidad de uso del software de diseo y funcionamiento y
prefieren vivir sin ella.

Los tiempos y las tendencias cambian constantemente. Lo mismo ocurre con las
directrices corporativas y leyes de aplicacin, que establece que un producto no puede
salir al mercado sin la documentacin. La documentacin es una parte de las reas clave
del proceso y no puede ni descartar ni dejado de lado por el momento el bienestar de
manera que pueda ser visto cuando hay tiempo para ello.