Generación de Documentación Técnica. (Informe

Universidad Simón Bolı́var
Departamento de Electónica y Circuitos
Laboratorio de Proyectos III EC3883
Enero-Marzo 2007, Sección 2.
Prof. Cecilia Murrugarra Q. cmquiroz@usb.ve
Generación de Documentación Técnica.
(Informe técnico, Protocolos de pruebas, Codificación de programas,
Bitácora, Cronograma de proyectos.)
Este documento solo pretende ser una guı́a o referencia rápida para la elaboración de documentación técnica de proyectos de Ingenierı́a. El mismo ha sido elaborado en base a mi
experiencia en la generación de documentación técnica de proyectos, productos y servicios y
de conversaciones sostenidas con otros colegas que dı́a a dı́a se enfrentan a este reto.
Este documento ha sido organizado en cuatro secciones que describo a continuación :
1. Informe Técnico. En esta sección se presenta el contenido básico que debe poseer el
informe técnico de un proyecto.
2. Bitácora ó Cuaderno de Bitácora. En esta sección se describe que és una Bitácora
y como puede ser organizada.
3. Cronograma del Proyecto. En esta sección se muestra una breve descripción de los
métodos más empleados para la generación de cronogramas de proyectos.
4. Documentación de Programas. En esta sección se presenta una referencia de
la información que deben contener los archivos de programas generados durante la
elaboración de un proyecto, de manera que permita rápidamente identificar ciertos
parámetros de programación y facilitar su lectura e interacción con todos los programas
de dicho proyecto.
1
Informe Técnico.
En esta sección se presenta el contenido básico que debe poseer el informe técnico de un
proyecto, de manera que la información reflejada en el mismo de una descripción del producto
que permita en todo momento conocer: ”Que és”, ”Que hace”, ”Como funciona” el producto
elaborado. Considero que la clave para obtener o generar una buena documentación técnica
rádica en estar consiente que la información reflejada debe permitir la reproducción exacta
del producto.
1. Descripción General.
• Identificación del Proyecto.
• Antecedentes y Justificación
• Objetivo General y Objetivos Especı́ficos
• Resultados Esperados (vista general de la presentación final del producto).
2. Diagrama de bloques de todo el sistema.
3. Esquemático de todo el sistema, diferenciando cada uno delos módulos del sistema.
1
4. Descripción Modular.
• Descripción.
• Diagrama esquemático, diagramas de estado o vistas (dependerá de lo que se este
presentando, un circuito, aplicación o una maqueta fı́sica).
• Lista de componentes, con especificaciones de tipo, potencia, etc. si se refiere a
un programa especificar plataforma de sistema operativo para su funcionamiento,
nombre y versión de la aplicación, requerimientos de memoria, espacio en disco o
periféricos indispensables para su funcionamiento, etc.
• Protocolos de pruebas para montaje y pruebas de funcionamiento del módulo.
5. Lista global de componentes y análisis de costos para un prototipo y para su producción en masa.(Se debe mantener la misma nomenclatura o codificación utilizada en las
descripciones anteriores.)
6. Protocolos de ensamblaje general de todos los módulos.
7. Protocolos de pruebas para el funcionamiento del producto.
2
Bitácora.
Es un registro escrito de las acciones que se llevaron acabo en cierto trabajo o tarea. Esta
bitácora incluye todos los sucesos que tuvieron lugar durante la realización de dicha tarea,
la fallas que se tuvieron, los cambios que se hicieron y los costos que ocasionaron.
Se recomienda utilizar un Cuaderno ó libreta de hojas tamaño carta con todas las páginas
numeradas correlativamente, donde se vaya plasmando el desarrollo diario del proyecto.
2.1
Organización.
Al inicio de la Bitacora es recomendable colocar una descripción general del producto que
se documentará, o que informe al lector cual es el alcance deseado.
Se recomienda seguir las siguientes indicaciones para mantener cierto orden:
• Identificar la fecha de inicio de cada sesión de trabajo.
• Identificar en base al nombre especificado en el informe técnico el nombre del módulo
donde se este trabajando.
• Agregar las hojas de descripción técnica (datasheets) y anexos que Ud. considere necesarios que permitan la reproducción del prototipo en desarrollo.
• En caso que se necesite eliminar información reflejada en la Bitacora, ésta debe ser
tachada, mas no eliminada del cuaderno !!.
3
Cronograma del Proyecto.
El cronograma del Proyecto muestra una descripción cronológica de los tiempos de ejecución
de cada una de las etapas empleadas para la elaboración del proyecto ó producto.
Anexo a la documentación técnica generada para el proyecto, debe presentar un esquema de
cronograma de ejecución del proyecto, para ello utilice diagramas gantt, pert, cpm u otro
2
similar. La dirección electrónica dada a continuación muestra una explicación y comparación
entre los diagramas usados en la planificación de proyectos.
http : //people.msoe.edu/ schroedp/se4900/slides/ControlCP M 1.ppt
4
Codificación de Programas.
La documentación sugerida aplica tanto a programas, librerı́as o funciones.
1. Membrete Inicial. El membrete inicial debe contemplar:
• El nombre y ubicación en disco, es decir el path o lugar donde estará almacenado
el archivo y su nombre con su respectiva extensión.
• Descripción general de su contenido, es decir, si es un programa indicar cual
es su funcionalidad, si es un conjunto de funciones para una aplicación especı́fica
que pueden ser recopiladas en un solo archivo indicar brevemente la descripción
de cada uno de ellas, por ejemplo funciones para el uso de un puerto paralelo, se
recomienda escribir una función que configure el puerto, otra que escriba un dato
en puerto y otra que reciba un dato en puerto, etc.
• Fecha de creación y nombre del autor.
• Fecha de modificación o actualización y el nombre del autor.
• Definición del área del membrete, se recomienda colocarla al inicio de cada
”programa”y encerrada ó enmarcada entre caracteres de comentarios.
2. Nombre de las funciones. Establecer algún tipo de codificación en forma de nmenónico
para la asinación de nombres de los archivos que conformen el conjunto de programas
de una aplicación, para ello se recomienda utilizar identificadores de 3 − 5 caracteres
que permitan al programador identificar rápidamente su contenido.
3. Ubicación ó almacenamiento en disco de los archivos generados. También es
recomendable que el programador establezca una especie de arbol no muy profundo
donde separe por direcorios el código fuente, los ejecutables, los archivos de datos, etc.
Para ello también puede usar nemónicos de tres caracteres como: src, bin,dat,lib,asm,
etc.
3