Departamento de Sistemas y Computación

INSTITUTO TECNOLOGICO de Morelia Documentación de software

Departamento de Sistemas y Computación 1

1 Introducción

El objetivo del presente documento es la especificación de una serie de lineamientos que

deberán observarse para el desarrollo de los diferentes productos de software en el

Departamento de Sistema y Computación del INSTITUTO TECNOLOGICO de Morelia.

Debe notarse, por una parte, que estas reglas constituyen un conjunto mínimo de los requisitos

para la documentación y organización de los productos de modo que el diseñador/programador

puede agregar más documentos si lo considera necesario; por otra parte, estos lineamientos

NO constituyen un reglamento estricto, sino un conjunto de normas flexibles que podrán ser

cambiadas de acuerdo con las necesidades que vayan surgiendo.

En este documento se entiende por un producto de software cualquier programa, paquete de

rutinas, rutina aislada o sistema completo que involucre programación (en cualquier lenguaje de

programación, inclusive de comandos).

Un paquete es un conjunto de rutinas, funciones y/o macros que versan sobre algún tema

particular; así pues, los elementos del paquete se relacionan entre sí sólo por el tema al que se

abocan y aunque algunas rutinas hagan referencia o llamen a otras, todas ellas son elementos

aislados que, en general, no requieren de las otras. Salvo por razones de prueba, un paquete

no se concreta en un programa ejecutable sino solamente como un conjunto de módulos objeto

y/o fuentes que pueden estar agrupados en bibliotecas.

Un sistema, a diferencia de un paquete, está constituido por un conjunto de elementos que

interactúan estrechamente, de tal manera que si alguno de ellos se elimina el sistema estará

incompleto y por ende su funcionamiento será inadecuado. Un sistema siempre se concretará

en un programa ejecutable.

2 Documentos

En los siguientes párrafos se describen brevemente los documentos mínimos que se requerirán

para la presentación de un producto de software. Entre paréntesis, después del título de cada

documento, aparece el nombre que éste deberá tener, siempre que se sustituya el asterisco (*)

por el nombre de su propio producto de software.

En el encabezado de todos los documentos se deberá indicar el nombre del archivo en que está

el documento, así como su localización. En los documentos en que hubiere figuras, éstas se

deben mantener en archivo electrónico si están digitalizadas, o bien en un fólder de papel, pero

en cualquier caso se debe indicar el método para obtener esas figuras.

2.1 Lenguaje de los documentos

Toda la documentación debe elaborarse en español.

2.2 Documentación de objetivos (*.dob)

En este documento se debe describir el objetivo del producto. Esta descripción consiste en la

especificación precisa del problema que el producto resuelve. El documento debe responder a

la pregunta ¿Para qué sirve este producto?

INSTITUTO TECNOLOGICO de Morelia Documentación de software

2 Departamento de Sistemas y Computación

2.3 Documento de requisitos (*.drq)

En este documento se deben establecer los requisitos del producto, esto es, se deben definir

claramente sus entradas y salidas así como los mecanismos para generarlas. En este

documento de define también el comportamiento externo del sistema, de la rutina o del conjunto

de rutinas del paquete, sin entrar al detalle de la forma o método empleado para la solución de

los problemas. El documento debe responder a la pregunta ¿qué debe hacer este producto?

2.4 Documento de análisis y diseño (*.dad)

Este documento debe contener todo el proceso de análisis del problema; es decir los métodos y

técnicas que se emplearon (o emplearán) para resolver el problema. Aquí se pueden incluir

referencias a otros documentos o artículos relacionados con el problema y que pueden dar más

luz sobre el asunto. Este documento debe ofrecer una visión clara de cuáles son los problemas

concretos que el producto deberá resolver y de qué forma serán éstos resueltos.

Todos los productos requieren de un documento de diseño que permita identificar claramente

cada una de las partes del producto y las interacciones entre ellas; ello puede implicar la

presentación de un diagrama conceptual del producto, en el que se viertan a manera de

bloques y flechas los elementos y las interacciones. En el caso de sistemas modulares, se

puede presentar un diagrama jerárquico de la estructura de esos sistemas. El documento debe

responder a la pregunta ¿Cómo lo hace?

2.6 Documentación del código

El código mismo del producto debe constituir un documento entendible. La documentación de

programas varía mucho dependiendo del estilo de redacción de cada diseñador. Esto no es tan

importante dado que los diferentes estilos pueden llegar a ser igualmente eficaces. Dada la

importancia de este punto en la sección 4 se citan las pautas que deben ser respetadas.

2.7 Manual de generación (*.dmg)

Este es un manual en el que se darán todas las indicaciones pertinentes para generar el

producto a partir de los archivos fuente. Se deben indicar aquí cuáles son los archivos fuente

(con directorios inclusive), los módulos objeto y bibliotecas que es necesario generar o, en caso

de existir, el procedimiento de comandos que es necesario correr para la generación automática

del paquete.

2.8 Manual de usuario (*.dmu)

Para todo paquete o sistema se deberá elaborar un manual de usuario en el que se indiquen los

pasos necesarios para emplear el paquete o sistema. Según el caso, deberán observar las

siguientes reglas:

Paquetes. Se debe especificar con claridad:

• Parámetros. Nombre y tipo del parámetro.

• Uso del parámetro, esto es, si el parámetro se usa como entrada, como salida, o si tiene

ambas funciones.

• Resultado de la función (tipo y significado del resultado), si tiene alguno y si no indicar

que no tiene resultado alguno.

• Archivos de encabezado que es necesario incluir (directiva include) para poder emplear

las rutinas.

• Módulos o bibliotecas con las que es necesario ligar para poder emplear las rutinas.

INSTITUTO TECNOLOGICO de Morelia Documentación de software

Departamento de Sistemas y Computación 3

2. Sistemas. En este caso se debe especificar:

• Forma de activar el sistema.

• Descripción de cada uno de los estados del sistema.

• Acciones para pasar de un estado a otro del sistema.

• Forma(s) para desactivar el sistema.

El manual deberá contar también con un buen número de ejemplos que ilustren

adecuadamente el uso del producto. Para el caso de paquetes, parte de la documentación

incluida en este manual puede ser tomada de la documentación que las mismas plantillas del

código obligan a incluir, pero debe notarse que no es la misma.

3 Organización del software

3.1 Directorios

Cada producto se asignará a un miembro del proyecto que fungirá como responsable del mismo

y esta persona puede tener asignados varios productos; por consiguiente, se sugiere la

siguiente organización para los archivos en directorios, para cualquier sistema operativo:

¨ \Nombre

Temp ProdA ProdB ProdC

Doc Código

Res

• Directorio nombre. Este es su propio directorio personal, a partir de aquí se deben crear

directorios para cada uno de los productos en desarrollo y además un directorio temp.

• Directorio prodx. Es el directorio correspondiente a cada uno de los productos y debe

llevar el nombre del producto que se está desarrollando. Este directorio contendrá por lo

menos dos subdirectorios, doc y código, pero además aquí se deben incluir los

procedimientos de comandos que permiten instalar y/o generar el sistema o paquete a

partir de los archivos fuente.

• Directorio doc. Este directorio debe contener toda la documentación relacionada con el

producto. Si la documentación incluye figuras, estas podrán guardarse en forma digital

en un archivo electrónico o podrán mantenerse en un archivo de papel aparte, pero aquí

se deberá indicar la forma en que se pueden recuperar u obtener esas figuras.

• Directorio código. Este directorio está destinado a ser recipiente para todos los archivos

fuentes del producto, objetos, bibliotecas y archivos de inclusión y si hay ejecutables,

estos también deberán estar en este directorio. En este directorio puede aparecer el

directorio res.

• Directorio res. Este directorio se define sólo para aplicaciones Windows o aquellas que

necesitan la definición de recursos de programación (menús, cajas de dialogo, iconos,

etc.)

INSTITUTO TECNOLOGICO de Morelia Documentación de software

4 Departamento de Sistemas y Computación

• Directorio temp. Este es un directorio en el que el propietario del árbol (nombre)

desarrollará todos los trabajos que estén pendientes para su transferencia al árbol de

directorios de otra persona, o aquellos que requieran de algún

...