Documentacin

Ing. de Software

Documentacin de software
A pesar de su importancia, las organizaciones productoras de software suelen descuidar la calidad de la documentacin de usuario. En muchos casos la documentacin se prepara en el ltimo minuto, y orientando su desarrollo ms como trmite que como herramienta de informacin para el usuario.

La Documentacin ayuda al cliente a obtener todo el valor de su inversin. La operacin de sistemas complejos sin un conocimiento detallado de los mismos
puede dejar sin uso un porcentaje importante de los mismos. Una documentacin completa y til incrementa la facilidad de uso del sistema.

LA PRODUCCIN DE DOCUMENTACIN DE USUARIO INADECUADA ES UN PROBLEMA COMN EN LA INDUSTRIA DEL SOFTWARE

Formatos
Interno
Documentacin de usuario que se encuentra integrada y es accesible a travs del software.

Formatos
Externo
Documentacin de usuario que cuyo acceso no est integrado en la operativa del software. El formato externo no quiere decir que emplee una distribucin no informtica, sino que se encuentra apartada de la operacin del software. De hecho la documentacin externa puede distribuirse en CD, a travs de descargas desde la web, etc.

Un documento puede abordar uno o varios de los siguientes mbitos:

Tipos

Instalacin / desinstalacin. Uso del sistema. (read me) Administracin. FAQ (preguntas frecuentes)

Un sistema de software puede disponer de manuales diferentes para cada uno de los subsistemas que lo componen.

Modos descriptivos
La documentacin de usuario puede adoptar dos modos narrativos diferentes: formativo o referencia,: Para aprender a trabajar con el software (modo formativo) Para refrescar la memoria, realizando consultas puntuales (modo referencia). Los textos formativos pueden orientar la exposicin de sus contenidos para indicar al lector cmo realizar cada tarea paso a paso. (orientados a tareas), o para transmitirle la informacin y conocimientos tcnicos necesarios para emplear el software de forma adecuada (orientados a la informacin).
Orientado a la informacin
Orientado a tareas
Modos descriptivos

Formativo

Referencia
6

Documentos necesarios
En funcin de las caractersticas del sistema, de los usuarios e incluso de parmetros del proyecto, es necesario determinar cules son los documentos que debern elaborarse. Algunos factores que pueden resultar tiles en su determinacin son: Naturaleza del producto, fin previsto, entorno en el que se emplear, complejidad de uso vista desde el punto de vista del usuario. Cmo de complejo es instalar, operar y mantener el sistema. Nivel de conocimientos de los usuarios, instaladores y personal de mantenimiento. En el uso de sistemas informticos. En los procesos y negocio gestionados por el sistema. Tamao y complejidad del sistema, junto con las tecnologas empleadas en su desarrollo y mantenimiento. Requisitos contratados. Ciclo de desarrollo del producto. As por ejemplo, un producto con desarrollo incremental puede tener como requisitos en el contrato la elaboracin de manuales de usuario para cada subsistema entregado, o uno global para todo el sistema.

Caractersticas de la audiencia o audiencias

Audiencia: grupo de usuarios con caractersticas similares, tanto de operacin con el sistema, como de conocimientos y experiencia informtica y profesional.

Antes de comenzar el desarrollo de la documentacin es importante clasificar a los usuarios del sistema por audiencias, identificando las caractersticas clave. La documentacin debe plantearse pensando en las caractersticas y necesidades de la audiencia. Algunos criterios tiles para identificar las audiencias y sus caractersticas:

Educacin:Cul es el nivel educativo de la audiencia? Actitud: Cul es la actitud de la audiencia?. Son reacios al uso de
ordenadores?. Presentan resistencia al cambio? Nivel de sofisticacin informtica. A ttulo de ejemplo, Brockmann identifica cinco niveles de sofisticacin informtica de los usuarios, que se muestran en la pgina siguiente. Familiaridad con los procesos y negocio de la aplicacin.
[1]

Clasificacin de usuarios

Nivel de sofisticacin informtica

Inexperto Parrot - Dummies

Caractersticas
Muy poca o ninguna experiencia con ordenadores Tratan volmenes reducidos de informacin No confan en la informtica Trabajadores concretos Alguna experiencia con ordenadores Pueden comprender conceptos aislados Emplean ejemplos concretos Emplean siempre las opciones por defecto Usuario novel con pocos meses de experiencia con ordenadores Comienza a enlazar conceptos aislados Emplea acciones por defecto y sus opciones. Es la evolucin de un usuario intermedio. Comprende las relaciones entre conceptos aislados. Tiene un nivel alto de autoconfianza. Comprende el lenguaje abstracto Puede ser inexperto, principiante, intermedio o experto. Trabaja muy poco con el sistema. Se conduce a travs de los mens y mensajes del sistema

Principiante

Intermedio

Experto

Intermitente

Documentar, de manera gil, pero documentar

Desde hace un tiempo llevo escuchando en varias empresas una curiosa frase, que viene a ser algo as como nosotros pensbam os que no necesitbamos documentar nada, porque utilizbamos metodologas giles (frase que se acompaa normalmente de las palabras SCRUM y/o XP), y que continua con pero el sistema fue creciendo y hemos perdido el control (control se acompaa de se fue un desarrollador y no sabemos como hizo parte del sistema, o de tenemos parte del desarrollo externalizado a una empresa y no sabemos que han hecho, por lo que no podemos prescindir d e ellos, o de integramos nuestro software con el de otra empresa, y no sabemos donde acaba un producto y empieza el otro, etc.) Los que leis desde hace tiempo este blog sabis que uno de sus objetivos, y tema recurrente, es evitar que modas superficiales sustituyan la base de ingeniera del desarrollo software, evitar que importantes errores en la gestin de proyectos software se sigan repitiendo, separar lo esencial de lo accidental, y, en definitiva, intentar ayudar en algo que sucede mucho en nuestra profesin: se empieza a correr la voz sobre una supuesta buena prctica que arregla todos los males, esta se empieza a usar sin control, y con el tiempo el proyecto acaba en alguno de los errores tpicos del desarrollo software. En este caso, la moda es la de no documentar nada. Recuerdo que hasta principios del 2000 la moda era documentar el diseo del software haciendo, literalmente, enciclopedias (que nadie lea y mucho menos se mantenan, yo particip en alguna de estas enciclopedias), y d e ah, en los ltimos aos, se ha puesto de moda el no documentar nada. Y, cmo suele suceder, ni blanco, ni negro, en el punto medio est la virtud, o lo que algunos llaman la documentacin gil. Y a este respecto, me ha parecido muy ajustado al tema un artculo que apareci en la IEEE Software de noviembre diciembre de 2009, de Bran Selic, titulado Agile Documentation, Anyone?, el cual se podra matizar en algn punto, artculo quizs algo polmico, y que a continuacin resumo y traduzco: Frecuentemente escucho a los desarrolladores decir que no les gusta documentar, que no lo encuentran til, pero No era el o bjetivo principal de documentar el ayudar a otros? Cmo es posible una visin tan distorsionada de la documentacin? Incluso escucho a los desarrolladores enorgullecerse del no documentes. Punto de vista que refleja el tan elogiado Manifiesto gil, que proclama: software que funcione, por encima de documentacin exhaustiva, como si fueran necesariamente excluyentes entre s. El propsito de la documentacin es ensear a quienes no estn familiarizados con un sistema cmo este se estructura, funciona y los motivos que llevaron a decidirse por ese diseo. Los principales usuarios de la documentacin de diseo son los futuros responsables del mantenimiento del sistema. La nica alternativa a no tener documentacin de diseo es explorar directamente el sistema, buscar un camino a travs de una selva sin mapa ni brjula. Tarea difcil, incluso cuando los autores del diseo estn disponibles para hacer de guas. Tambin ineficaz, ya que estos autores tienen que explicar el diseo una y otra vez. As, mientras que documentar tiene un coste, la inversin, si se hace correctamente, vale la pena. Pero, sin embargo, en la prctica, la tendencia parece que va en la direccin opuesta. La razn que se argumenta es la dificultad de mantener la documentacin sincronizada con algo tan dinmico como es el software, y que el coste de documentar se podra utilizar en generar ms cdigo (software que funcione, por encima de documentacin exhaustiva). Por ltimo, hay quienes argumentan que el cdigo es la nica documentacin, que es el nico que contiene la realidad. La industria del software est repleta de historias sobre viejo cdigo heredado que nadie se atreve a tocar, porque nadie lo entiende. La semntica de los lenguajes de programacin est muy lejos de la semntica del dominio de aplicacin. La amplitud de esta brecha es la razn por la que todava se necesitan programadores. La preferencia del Manifiesto gil por el cdigo por encima de la documentacin, slo se opone a una categora especfica de documentacin de diseo: los documentos voluminosos y detallados que describen implementaciones, previas a comprender el problema o tener experiencia con la solucin. Los documentos de este tipo se vuelven rpidamente obsoletos, y gran parte del esfuerzo invertido en la produccin y actualizacin de ellos se pierde. Como seal Helmuth von Moltke: Ningn plan sobrevive al primer contacto con el enemigo. Sin embargo, la ineficacia de los primeros documentos de diseo, no es argumento para su eliminacin. En el desarrollo gil se llega a la comprensin mediante la experimentacin con el sistema software, sin duda una de las maneras ms efectivas de aprender. Sin embargo, esta manera de aprender slo est disponible para los diseadores que crearon el diseo, y no para aquellos que les seguirn y que no han podido participar directamente en la creacin del diseo. Documentar el software en el cdigo es imprudente, redunda en la pesadilla de intentar mantener la duplicacin de informacin coherente. Necesitamos documentos de diseo a un mayor nivel de abstraccin, sin detalles tecnolgicos innecesarios y estrechamente asociados a conceptos del domino y los requisitos. Estos documentos no slo ayudan a ver el bosque que se oculta en el mar de cdigo, tambin a documentar los principios bsicos del diseo y a servir como el principal medio de comunicacin entre los actores del sistema. Con la excepcin de los sistemas relativamente pequeos, llevar el diseo de alto nivel en el cdigo (como recomienda, por ejemplo, Extreme Programming) es imprudente. Debiera haber documentacin de diseo gil, que mantenga y enlace el diseo y la codificacin. Y el esfuerzo realizado en documentar debiera ser proporcional al tamao del diseo.