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.

...