Software Garden

Muchas veces me ha tocado no sólo desarrollar una aplicación sino escribir la documentación para el usuario final y para la gente de sistemas que eventualmente tenga que mantener ese desarrollo. A lo largo de los años he llegado a algunas conclusiones que expongo a continuación.

Tipos de Documentación

Es importante diferenciar claramente entre los distintos tipos de documentos encargados de describir una aplicación ya que los objetivos de cada uno son muy diferentes.

La documentación para el desarrollador que describe desde un punto de vista técnico el funcionamiento de la aplicación. Por otro lado está la documentación para el usuario, que describe cómo se utiliza la aplicación. Estas son las dos áreas de documentación más importantes.

En algunas ocaciones se crean otro tipo de documentos que de alguna forma estén relacionados con la aplicación como, por ejemplo, documentación especial para operadores de centros de cómputos, administradores de redes o de bases de datos.

La documentación para el desarrollador

En estos documentos predomina un lenguaje técnico y está dirigida a programadores, analistas de sistemas.

Esta documentación debe cumplir, entre otros, los siguientes objetivos:

• 
  

  Proporcionar una descripción cabal de la función, la estructura y la forma de trabajo de cada módulo de la aplicación.

  
  


• 
  

  Describir la organización del programa a partir de sus módulos componentes.

  
  


• 
  

  En la industria informática, la mayor parte de las grandes aplicaciones se escriben en equipo, y la documentación debe permitir a cada integrante del equipo comprender el funcionamiento aún de los módulos en los que no está involucrado.

  
  


• 
  

  Aportar a cualquiera que no haya participado en el proyecto desde el inicio, incorporarse en cualquier momento al mismo y tener información suficiente para entenderlo y modificarlo.

  
  


• 
  

  Contribuir a la evaluación de la aplicación y a la determinación de si cumple los objetivos para la que se creó.

  
  

Redactar un documento de estas características no es fácil. Algunas sugerencias para facilitar la escritura pueden ser:

• 
  

  Antes de empezar a escribir la documentación es conveniente tomarse un tiempo para pensar en la estructura que tendrá la misma en general y cada documento en particular.

  
  


• 
  

  Al estructurar un documento es importante separar claramente “qué hace” un programa o módulo de “cómo lo hace”.

  
  


• 
  

  Aunque la documentación debe ser completa y abarcar todos los aspectos del desarrollo, en ocaciones el exceso de detalle puede ser desconcertante. Es conveniente tener en cuenta que el máximo nivel de detalle son las propias líneas de código de cada programa. Un programa bien diseñado y escrito en los actuales lenguajes de alto nivel como VB.Net o C# y con comentarios suficientes dentro del código, constituye en cierta forma su propia documentación. Dicho de otra forma, el programa describe su estructura y su forma de trabajo.

  
  


• 
  

  Estos documentos van dirigidos a una audiencia experta y no hay problemas en utilizar términos técnicos y dar algunas cosa por sabidas. Sin embargo la extrema utilización del lenguaje técnico sirve muchas veces para cubrir la extrema pobreza del español de quien esta escribiendo el documento. No hay ninguna excusa para que la documentación sea escrita en un lenguaje simple y un estilo claro y conciso.

  
  

Dependiendo de la naturaleza de la aplicación que se está documentando, se pueden incluir diagramas de flujo, de estructuras de datos, de objetos, etc… Pero estos diagramas no deben reemplazar a los documentos sino apoyarlos y aclararlos.

Documentación para el usuario

Esta información contiene las instrucciones necesarias para utilizar la aplicación desarrollada. Va dirigida a los usuarios que, en general y a pesar de lo que muchos creen, tienen un conocimiento limitado en el uso de las computadoras y las aplicaciones.

La documentación para el usuario es mucho más dificil de escribir que la dirigida al desarrollador. Hay que evitar al máximo el lenguaje técnico y hacer uso intensivo de imágenes y diagramas, ya que el usuario es más reacio a leer documentos largos y muy verborrágicos.

La forma que adopte esta documentación depende en gran medida del tipo de aplicación que se esté documentando. Lo ideal es presentarla en papel y en algún tipo de formato electrónico para cubrir todas las opciones.

Algunos objetivos que deben cumplir estos documentos son:

• 
  

  Informar al usuario de forma clara y sin que quede ninguna duda de las capacidades de la aplicación.

  
  


• 
  

  Proporcionar instrucciones detalladas paso a paso sobre cada una de las funciones que se pueden realizar con la aplicación.

  
  


• 
  

  Explicar claramente el significado de cada mensaje que pueda aparece y las acciones a seguir ante cada uno, en especial con los mensajes de error.

  
  


• 
  

  Señalar claramente como solucionar los errores no sólo dentro de la aplicación sino externos a ella, que pudieran influir en su funcionamiento.

  
  


• 
  

  Separar “qué hace” cada módulo de la aplicación de “como lo hace”.

  
  


• 
  

  Explicar en un glosario todos los términos técnicos que no fue posible evitar usar.

  
  


• 
  

  Redactar de forma clara, en un español sencillo y hacer uso intensivo de diagramas, capturas de pantalla y ejemplos.

  
  

Conclusiones

La documentación para el desarrollador describe a nivel técnico el funcionamiento de la aplicación, su estructura, la relación entre sus diferentes módulos y como funciona cada uno en detalle. Uno de sus principales objetivos es que cualquier desarrollador o profesional de sistemas pueda comprender y mantener la aplicación aunque no haya participado en el desarrollo de ella desde el principio.

La documentación para el usuario contiene las instrucciones necesarias para la utilización de la aplicación. Informa las posibilidades de esta y describe paso a paso el uso de cada módulo. Una de las funciones más importantes es describir detalladamente las acciones a seguir ante cualquier error que pueda presentarse. Debe estar escrita en un lenguaje simple y claro y debe adaptarse a la capacidad y conocimiento del usuario medio a la que se dirige.

Saludos.