La importancia de la

documentación de software
«A nadie le gusta escribir documentación». Cualquiera que
esté relacionado con la industria del software escuchará esta
frase al menos un par de veces al año. Esta frase lo hace
sonar como si se tratara de una actividad tediosa pero
necesaria como hacer limpieza de primavera. Sin embargo la
mayor parte de esta industria simplemente no hace
documentación.
Cesar Paternosto

¿Por qué a nadie le gusta hacer

documentación?
Desde mi punto de vista, quienes desarrollan repudio hacia
la documentación son los que no saben qué es.
Tiene el estigma de ser un conjunto de documentos
aburridos y redundantes impuestos por la
Ingeniería de Software que sólo le quitan el tiempo
al programador ya que en realidad nadie va a
leerlos.

Tiene también mucho peso el hecho de que es común que

una persona que trabaje en esta industria no está habituada
a la lectura. Aquí podría pensarse que esto es debido a los
problemas que tiene el sistema educativo del país. Quiero
ser claro en que este no es un problema exclusivo de México.
Sin importar el país, es común encontrarse con personas
que creen que una lista de funciones en un correo
electrónico cuenta como hacer llegar la documentación.
También es común que las personas cuyo trabajo
es dirigir a un equipo de programadores no tengan
el perfil necesario. No aprenden algo de
programación, no están al tanto de las tecnologías
que su propia empresa emplea, no se interesan por
saber cómo es que el producto que venden
funciona. Es normal que estas personas caigan en
el error de creer que no tienen responsabilidad
sobre la documentación.

¿Qué es la documentación?
Para mantenernos lejos de tecnicismos, la
documentación de un software es el registro de
todo lo que ocurrió en la implementación de una
solución.
Paternosto

Nótese que usé el pretérito: ocurrió. Para mi, documentar

software se parece más a la bitácora que lleva consigo un
grupo que explora el mundo. Por supuesto que hubo una
planeación antes de salir, pero todos los días hay que tomar
decisiones, surgen contratiempos, las prioridades cambian.
Si un programador tiene que escribir una
función complicada, debería existir algo que
explique en términos sencillos porqué se
tomaron ciertas decisiones, cómo se
resolvieron los problemas y qué queda
pendiente. En el futuro, alguien tendrá que
volver al mismo punto y necesitará entender
qué fue lo que se hizo. Aunque esa persona
sea el mismo programador, si ha pasado
suficiente tiempo, será una persona
completamente nueva.

¿Por qué hacer documentación?

El producto no es el software (así que dejen de patentarlo).
Nadie en este mundo despierta un día y dice «Quiero
exactamente este conjunto de instrucciones corriendo en
una computadora». Lo que sí ocurre es que alguien descubre
que tiene una necesidad y busca una solución.
El producto es el sistema; una serie de reglas que
resuelven la necesidad. ¿En qué es distinto esto de
cualquier otra industria? Bueno, ¿alguien alguna
vez ha visto un sistema? No, nadie. El sistema no es
tangible. No podemos decir nada de él usando
nuestros sentidos ya que ninguno funciona con lo
abstracto.

¿Qué seguridad tenemos para mirar al cliente a los ojos y

decirle que su necesidad está resuelta? Claro, están las
pruebas. Pero eso sólo nos dice que el software funciona. La
pregunta más importante es: si el sistema vive en el mundo
de las ideas, ¿cómo sabemos que todos estamos hablando
del mismo?

Paternosto

Este es el objetivo principal de la documentación de

software. Ayudar a un equipo a adentrarse por un terreno
que no puede ser visto ni tocado. Al describir lo mejor
posible el camino en alguna forma accesible podemos: guiar
a todos los que pasarán por el mismo lugar, saber a dónde
hemos llegado y planear hacia dónde queremos ir.

Esta es la razón por la que voy a seguirme sorprendiendo

cada que alguien me diga que no tiene documentación. Si el
grupo de exploradores no tiene mapas, entonces no tiene
idea de dónde está.

¿Cómo hacer documentación?

Esta no es una pregunta sencilla. Depende de varios
factores:

 Es importante conocer al equipo: Formación académica,

personalidad, capacidad de trabajo en equipo…
 Área de la industria. La industria determina el tipo de
producto y esto influye en las prioridades de
documentación. En un sistema de contabilidad hay que
asegurar que son claras las operaciones que se
requerirán. Un videojuego tendría que registrar cómo se
logró que los gráficos llegaran tan rápido a la memoria.
 Alcance. ¿Hasta dónde necesitamos que llegue el
sistema? Tal vez algún día se conectará con otro. Si la
necesidad cambia, ¿se planea que el software sea
desechado o ampliado?

Existen distintas metodologías sobre cómo hacer

documentación. Aunque sí es importante estudiarlas, lo
principal es evaluar qué funciona y qué no. No es inteligente
seguir ciegamente una metodología sólo porque así lo dice la
certificación o el libro. Las circunstancias nunca van a ser las
mismas que las del autor de la metodología.
Se deben escoger documentos que ayuden a que la
implementación sea más rápida. Por ejemplo,
cuando un equipo debe usar código escrito por
otro. Un documento evita tener que preguntar o
revisar el código de alguien más.
Paternosto

Si soy líder de equipo

El principal error que veo en líderes de equipo es sólo
preocuparse por hablar con el cliente (o jefes). Es
importante que sepan que su trabajo no es presentarse a
juntas. Su trabajo es cuidar la expedición. Eso los hace
responsables de la salud tanto del proyecto como del
personal.

Deben estar claros los objetivos. Y sobre todo, debe estar

claro que el conjunto de objetivos es realmente el que el
cliente requiere. Esto se registra en documentación de
requerimientos, como documentos de historias de uso. El
líder tiene que asegurarse de que el cliente está de acuerdo
con el documento y que este es claro para el equipo.

El líder también debe participar en la documentación de

diseño y arquitectura. Esta documentación explica el
funcionamiento en general del sistema, descripción del
ambiente y principios de desarrollo. La función de estos
documentos es que quede claro para cualquier persona con
un conocimiento básico de desarrollo entender cómo está
construido el software así como qué es capaz de hacer y qué
no.

Si soy programador
Un programador está en constante contacto con
documentación. Principalmente documentación técnica que
es la que lleva registro del código. Esto ya sugiere cómo
debería de verse la documentación del trabajo que está
realizando.

La documentación técnica debe ahorrarle tiempo a alguien

más, recordemos que ese alguien puede ser el mismo
programador en el futuro. Registrar nombres y
descripciones de funciones, nombres de parámetros,
mensajes…
El programador también participa en la documentación de
requerimientos y de diseño y arquitectura, cuidando que
todo lo descrito esté fundamentado y dentro de lo real.

Escribir tutoriales y notas técnicas en un blog es buen

ejercicio para desarrollar habilidades de redacción,
consumir otro tipo de literatura como novelas e inspirarse
con la documentación de las tecnologías que se estén
empleando.

Si soy el cliente
Cuando se inicia un proyecto, el primer paso es entender a la
perfección la necesidad a resolver. Este proceso hace al
cliente parte del equipo de desarrollo y se requiere de la
participación de todos para lograr plasmar la mejor
descripción del sistema. Porque el sistema debe sobrevivir al
software. Nuevas tecnologías siempre llegarán a reemplazar
a las viejas. Pero si el sistema está bien documentado, no
será necesario iniciar la expedición desde el mismo punto de
origen.

En Jaque, contamos con un proceso de

desarrollo que se auxilia de un protocolo de
documentación que constantemente está
siendo optimizado en función de los avances
tecnológicos y las necesidades de cada uno
de los proyectos para que así, cada sistema
pueda vivir el tiempo que la necesidad esté
presente.
 Importancia de la documentación
 Por Sara Alvarez


 06 de julio de 2006
 5 Comentarios
 Desarrollo
Describimos los aspectos claves para el desarrollo de una
buena documentación del programa a entregar al cliente.
La documentación de los programas es un aspecto sumamente importante,
tanto en el desarrollo de la aplicación como en el mantenimiento de la misma.
Mucha gente no hace este parte del desarrollo y no se da cuenta de que pierde
la posibilidad de la reutilización de parte del programa en otras aplicaciones, sin
necesidad de conocerse el código al dedillo.

La documentación de un programa empieza a la vez que la construcción del

mismo y finaliza justo antes de la entrega del programa o aplicación al cliente.
Así mismo, la documentación que se entrega al cliente tendrá que coincidir con
la versión final de los programas que componen la aplicación.

Una vez concluido el programa, los documentos que se deben entregar son
una guía técnica, una guía de uso y de instalación.

Tipos de documentación

La documentación que se entrega al cliente se divide claramente en dos

categorías, interna y externa:

 Interna: Es aquella que se crea en el mismo código, ya puede ser en forma de

comentarios o de archivos de información dentro de la aplicación.
 Externa: Es aquella que se escribe en cuadernos o libros, totalmente ajena a la
aplicación en si. Dentro de esta categoría también se encuentra la ayuda electrónica.
La guía técnica

En la guía técnica o manual técnico se reflejan el diseño del proyecto, la

codificación de la aplicación y las pruebas realizadas para su correcto
funcionamiento. Generalmente este documento esta diseñado para personas
con conocimientos de informática, generalmente programadores.

El principal objetivo es el de facilitar el desarrollo, corrección y futuro

mantenimiento de la aplicación de una forma rápida y fácil.
 Esta guía esta compuesta por tres apartados claramente diferenciados:

 Cuaderno de carga: Es donde queda reflejada la solución o diseño de la aplicación.

Esta parte de la guía es únicamente destinada a los programadores. Debe estar
realizado de tal forma que permita la división del trabajo
 Programa fuente: Es donde se incluye la codificación realizada por los programadores.
Este documento puede tener, a su vez, otra documentación para su mejor comprensión y
puede ser de gran ayuda para el mantenimiento o desarrollo mejorado de la aplicación.
Este documento debe tener una gran claridad en su escritura para su fácil comprensión.
 Pruebas: es el documento donde se especifican el tipo de pruebas realizadas a lo largo
de todo el proyecto y los resultados obtenidos.
La guía de uso

Es lo que comúnmente llamamos el manual del usuario. Contiene la

información necesaria para que los usuarios utilicen correctamente la
aplicación.

Este documento se hace desde la guía técnica pero se suprimen los

tecnicismos y se presenta de forma que sea entendible para el usuario que no
sea experto en informática.

Un punto a tener en cuenta en su creación es que no debe hacer referencia a

ningún apartado de la guía técnica y en el caso de que se haga uso de algún
tecnicismo debe ir acompañado de un glosario al final de la misma para su fácil
comprensión.

La guía de instalación

Es la guía que contiene la información necesaria para implementar dicha

aplicación.
Dentro de este documento se encuentran las instrucciones para la puesta en
marcha del sistema y las normas de utilización del mismo.

Dentro de las normas de utilización se incluyen también las normas de

seguridad, tanto las físicas como las referentes al acceso a la información.
 Sistema deDocumentación

TÈCNICAS Y ELEMENTOS DE DOCUMENTACIÒN DE SISTEMAS

INTRODUCCIÓN

En el mundo globalizado de hoy es necesario que las empresas, instituciones públicas, entre
otros, cuenten con un sistema documental de sus procedimientos,servicios y funciones; ya que
la documentación es el soporte del sistema de gestiónde la calidad y planificación, pues en ella
se plasman no sólo las formas de operar dela organización sino toda la información que
permite el desarrollo de todos los procesos, la toma de decisiones y permitir las
auditorías.Existen diversas técnicas, elementos y metodologías con los cuales se
puedeelaborar la documentación que nos permita atacar las necesidades que tenga cualquier
tipo de organización o cliente; de manera tal que la documentación a implementar cumpla con
los requisitos, permita el desarrollo y la permanencia en el mercado.Con la documentación se
puede mantener y actualizar los sistemas deinformación de una empresa frecuentemente, con
el fin de brindar efectividad en eldiseño de las estrategias; un buen sistema de documentación
debe desarrollarseutilizando un método único, estandarizado que proporcione una
comunicación clara yrápida, ya que pueden reducir costos en el almacenamiento,
adiestramiento de personal, adquisición de tecnologías y otros.A continuación señalaremos los
aspectos que tienen que ver con las técnicas yelementos de la documentación de

Sistema deDocumentación

TÈCNICAS Y ELEMENTOS DE DOCUMENTACIÒN DE SISTEMAS

INTRODUCCIÓN

En el mundo globalizado de hoy es necesario que las empresas, instituciones públicas, entre
otros, cuenten con un sistema documental de sus procedimientos,servicios y funciones; ya que
la documentación es el soporte del sistema de gestiónde la calidad y planificación, pues en ella
se plasman no sólo las formas de operar dela organización sino toda la información que
permite el desarrollo de todos los procesos, la toma de decisiones y permitir las
auditorías.Existen diversas técnicas, elementos y metodologías con los cuales se
puedeelaborar la documentación que nos permita atacar las necesidades que tenga
cualquier tipo de organización o cliente; de manera tal que la documentación a
implementar cumpla con los requisitos, permita el desarrollo y la permanencia en el
mercado.Con la documentación se puede mantener y actualizar los sistemas deinformación de
una empresa frecuentemente, con el fin de brindar efectividad en eldiseño de las estrategias;
un buen sistema de documentación debe desarrollarseutilizando un método único,
estandarizado que proporcione una comunicación clara yrápida, ya que pueden reducir
costos en el almacenamiento, adiestramiento de personal, adquisición de tecnologías y otros.A
continuación señalaremos los aspectos que tienen que ver con las técnicas
yelementos de la documentación de