Gua para la documentacin

de proyectos de software
Organizacin de Computadoras
Universidad Nacional del Sur
2017

Estructura y contenido

1. Definiciones y especificacin de requerimientos

Los requerimientos/requisitos de un sistema describen los servicios que ha de ofrecer el sistema y las
restricciones asociadas a su funcionamiento, es decir, las propiedades o restricciones que deben
satisfacerse, determinadas de forma precisa.

En este apartado se brindarn tres aspectos informativos:

a) Definicin general del proyecto de software: explicar en qu consiste el sistema o desarrollo en

cuestin, cul es la idea general y la funcionalidad principal del proyecto de software, as como
tambin los propsitos y objetivos del desarrollo.
b) Especificacin de requerimientos del proyecto: incluir el detalle de los requerimientos tcnicos
y generales del mismo (por ejemplo, en el caso de un proyecto de software de la UNS, las
consignas y pautas del mismo), los alcances y limitaciones de la implementacin realizada.
Deber aclararse si el proyecto de software forma parte de algn sistema ya desarrollado; de
ser el caso, especificar si se desarroll una nueva versin o es una derivacin.
c) Procedimientos de instalacin y prueba: detallar cmo se realiza la obtencin, instalacin y/o
prueba del sistema, junto las especificaciones generales de la plataforma o el entorno sobre el
cual el software debe ser ejecutado.

De la definicin general del proyecto de software

En la definicin del proyecto se deber brindar detalle sobre los puntos que se definen a continuacin:

Idea general: la funcionalidad principal del sistema (qu..?)

Objetivos: los objetivos del desarrollo, y la necesidad cubierta por el sistema en cuestin (para
qu..?)
 Usuarios: las personas o entidades que utilizarn el sistema o parte de l, y el nivel de
experiencia del usuario hacia el cual el presente informe est dirigido (quin..?)

De las especificacin de requerimientos del proyecto de software

Dentro de la especificacin de requerimientos se dar informacin del proyecto de software sobre los
siguientes puntos:

Requisitos generales: las pautas y consignas que sigue el proyecto de software.

Requisitos funcionales: los servicios que el sistema proporciona, las tareas que ste desarrolla.
Informacin de autora y Legacy del proyecto: explicitar si el proyecto de software forma parte
de desarrollos previos/preexistentes o si es original, y en el caso correspondiente, detalles de
retro-compatibilidad.
Alcances del sistema: las limitaciones y alcances del desarrollo, de acuerdo a los objetivos
previamente establecidos.

De las especificaciones de procedimientos

Dentro de la informacin relativa a procedimientos se distinguir:

Procedimientos de desarrollo:
Herramientas utilizadas: entornos de desarrollo integrados, plataformas y herramientas
empleadas en la implementacin del sistema.
Planificacin: una descripcin global de la metodologa utilizada para encarar y resolver el
problema; por ejemplo: los pasos ejecutados a lo largo de la resolucin del proyecto, a grandes
rasgos.

Procedimientos de instalacin y prueba:

Requisitos no funcionales: si las hubiere, restricciones que afectan el normal desempeo del
sistema.
Obtencin e instalacin: una gua sencilla que explique el procedimiento bsico para obtener e
instalar el sistema. La gua debe estar dirigida a usuarios con nivel de experiencia preestablecido
en la definicin general del proyecto.
Especificaciones de prueba y ejecucin: datos tcnicos sobre la plataforma y/o entornos a
utilizar en la prueba o ejecucin del software en cuestin.
1. Arquitectura del sistema

Incluso un software de tamao pequeo consta de la composicin de varios mdulos o partes

interconectados de alguna forma. La descripcin de la arquitectura del sistema informa sobre cules
son estas partes, qu rol tienen dentro del software y la forma en que estas se organizan e
interconectan.

La informacin sobre la arquitectura debera incluir como mnimo:

Descripcin jerrquica: Indica de qu forma se organizan jerrquicamente los componentes del

sistema. Es decir, indicar si los mismos estn organizados en paquetes, espacios de nombres o
bien si el software posee una estructura monoltica.

Diagrama de mdulos: Consiste en un diagrama donde se representan todas las partes que
componen el sistema y las relaciones que existen entre estas. El objetivo de este diagrama
consiste en presentar una perspectiva global de la arquitectura y los componentes del sistema,
no debera contener detalles tcnicos sobre los mdulos o las conexiones entre estos.

Descripcin individual de los mdulos: Para cada mdulo o parte del sistema, se debera
realizar una breve descripcin del mismo, la cual debera incluir mnimamente:

Descripcin general y propsito: qu es y qu debera hacer el mdulo?

Responsabilidad y restricciones: cul es su funcin especfica dentro del sistema? qu
cosas puede y no puede hacer?
Dependencias: Indicar cuales son los requisitos del mdulo, es decir se debe contestar a
preguntas tales como qu necesita o requiere el mdulo para funcionar? necesita de
servicios brindados por otros mdulos o por libreras externas?
Implementacin: indicar en qu archivo o archivos se encuentra la implementacin del
mdulo.

No es el objetivo de esta seccin dar detalles de cmo se realiza la implementacin de los

mdulos, sino nicamente dar una idea general de para qu existe el mdulo dentro del
sistema.

Dependencias externas: Si el software utiliza libreras o servicios externos estos deben listarse
junto con una breve descripcin de las mismas.
 Adicionalmente en esta seccin se deben listar los aspectos tcnicos o tecnologas empleadas en el
proyecto, tales como el lenguaje de programacin, frameworks, libreras, etc.
Puede resultar de utilidad incluir junto a estos una breve descripcin de las decisiones de diseo
asociadas que llevaron a elegir la o las tecnologas en particular, es decir responder a por qu se utiliz
esta tecnologa y no otra?

1. Diseo del modelo de datos

Distinguir cules son las entidades involucradas en el sistema y mencionarlas en un formato language-
agnostic.
Puede ser un diseo orientado a objetos, relacional, etc., lo importante es tener una idea general del
modelo de datos: entidades, atributos y las relaciones entre ellas. Para ello es imprescindible incluir
diagramas o grficos que ayuden a visualizar el modelo de datos.

Un programa, aplicacin o librera puede a su vez trabajar con varios tipos de datos:

- Datos de entrada.
- Datos internos.
- Datos de salida.

Distinguir claramente cada uno de ellos y describir su modelo.

1. Descripcin de procesos y servicios ofrecidos por el sistema

Mencionar cules son los servicios o tareas que el sistema ofrece/implementa, y describir los procesos
que realizan, para entender cmo funcionan, y cmo se pueden invocar/utilizar.

Para este propsito es conveniente incluir pseudo-algoritmos, diagramas de flujo, etc.

Tener presente que la descripcin del proceso no significa mostrar el cdigo, ni consiste tampoco
brindar detalles especficos de cmo lo hace (funciones utilizadas para hacer cierta tarea) sino de
explicar brevemente qu hace o cul es su propsito. Se espera tambin una descripcin de los datos
de entrada y salida (Cantidad de argumentos, tipo y significado de cada uno).

En este punto es imprescindible que el cdigo fuente de la aplicacin est enriquecido con comentarios.
Estos deben conformar la documentacin bsica de todo proyecto, y a partir de los mismos debera
poder construirse la descripcin de alto nivel del funcionamiento de los procesos y servicios del
sistema, as como sus funciones, subrutinas, mdulos, clases, etc.
 2. Documentacin tcnica - Especificacin API

Se indica el propsito y breve descripcin de cada mtodo/funcin, con su prototipo indicando

argumentos (nombre, tipo, propsito de cada uno) y respuesta (tipo, descripcin).

Para llevar a cabo esta tarea, es posible utilizar una variedad de herramientas de generacin de
documentacin automtica, a partir del cdigo en el encabezado de cada funcin (por ejemplo
Javadoc, PHPDoc, Doxygen, etc).

La documentacin tcnica debe pensarse como el manual del programador, y debe apuntar a aquellas
personas que estarn a cargo de mantener, ampliar, o crear un proyecto derivado a partir de nuestro
proyecto.

Aspectos relevantes

Indicar claramente cmo invocar el programa (signatura del programa completa, como la que hara
cualquier sinopsis de una pgina de manual), conteniendo qu parmetros son opcionales, cuales son
obligatorios, y documentar bien cul es la utilidad de cada parmetro y cul es el comportamiento por
defecto si se omite algn parmetro opcional. Esto conforma comnmente el manual del usuario final
de la aplicacin.
Incorporar diagramas de flujo y explicaciones a nivel mtodo de la solucin, debe explicarse la
estrategia general de resolucin donde se pueda apreciar cmo interactan los mdulos entre s.
Los tipos de datos abstractos (TDAs) deben estar adecuadamente documentados en el cdigo, por otra
parte, en el manual deben constar las limitaciones posee la representacin, cmo se representa una
determinada estructura y detalle de mtodos que provee el TDA para la manipulacin de los datos.
Incluir una seccin de Conclusiones, donde se deben resumir complicaciones encontradas durante el
desarrollo del proyecto, polticas adoptadas para su resolucin, restricciones al problema original, casos
particulares y finalmente aspectos relacionados a la experiencia obtenida en base a la temtica del
proyecto.

Herramientas

Existen aplicaciones que permiten la generacin automtica de documentacin para cdigo en lenguaje C,
entre las mismas se puede citar el programa Doxygen http://www.doxygen.org.