Está en la página 1de 14

DOCUMENTACIN DE SISTEMAS 1.

INTRODUCCIN La documentacin de sistemas es el conjunto de informacin que nos dice qu hacen los sistemas, cmo lo hacen y para quin lo hacen. La documentacin consiste en material que explica las caractersticas tcnicas y la operacin de un sistema. Es esencial para proporcionar entendimiento de un sistema a quien lo vaya a usar para mantenerlo, para permitir auditoria del sistema y para ensea r a los usuarios como interactuar con el sistema y a los operandos como hacerlo funcionar. Existen varios tipos de documentacin. La de programas, que explica la lgica de un programa e incluye descripciones, diagramas de flujo, listados de programas y otros documentos; la del usuarios en forma general la naturaleza y capacidades del sistema y cmo usarlo. Muchas organizaciones tienen lo que se conoce como un " programa de documentacin", el cual consiste en una poltica formal cuya documentacin se muestra como algo que debe prepararse en forma rutinaria para cada programa de cmputo, archivo y nuevos sistemas. Otra definicin sera la de registro fsico, generalmente por escrito que contiene los siguientes elementos: Polticas y normas referentes al desarrollo del sistema, su implantacin, operacin y mantenimiento. El diseo del sistema de informacin administrativo. Procedimientos para instalar el sistema de informacin administrativo. Procedimientos para operar el sistema de informacin administrativo. Procedimientos para mantener el sistema de informacin administrativo.

IMPORTANCIA DE LA DOCUMENTACIN DE SISTEMAS La importancia de la documentacin bien podra ser comparada con la importancia de la existencia de una Pliza de Seguro; mientras todo va bien no existe la precaucin de confirmar si nuest ra Pliza de Seguros est o no vigente. La documentacin adecuada y completa, de una aplicacin que se desea implantar, mantener y actualizar en forma satisfactoria, es esencial en cualquie r Sistema de Informacin, sin embargo, frecuentemente es la parte a la cual se dedica l menor tiempo y se le presta menos atencin. Siempre se debe documentar un sistema como si estuviera a punto de irse a Siberia el siguiente mes, para nunca volver. Si la documentacin del sistema es incompleta el diseador continuamente estar involucrado y no podr moverse a otra asignacin.

2. ESTANDARIZACIN Y NORMALIZACIN

Estandarizacin Significa que los smbolos convencionales se usan en todos los diagramas de flujo para prescribir el sistema y que en la documentacin se usen formas estandarizadas. An cuando las normas de documentacin varan de una instalacin a otra, es esencial que dent ro de una organizacin, se utilice un solo mtodo. El uso de procedimientos y documentacin estandarizada proporciona la base de una comunicacin clara y rpida, adiestramiento menos costoso del personal de sistemas, reduccin de costos de almacenamiento, y otros. VENTAJAS DE LA ESTANDARIZACIN Ayuda al entrenamiento del nuevo personal dentro y fuera de la organizacin de Sistemas. Es til para cualquiera que tenga la responsabilidad del mantenimiento de los sistemas. Ayuda a los analistas y diseadores de sistemas en el trabajo de integracin de sistemas. Asegura que el sistema opere correctamente. Se utilizan eficientemente los recursos que se dispongan. ESTNDARES BSICOS DE DOCUMENTACIN Toda documentacin que se relacione con un sistema, ya sea manual o por computadora, sencillo o complejo debe reunir los siguientes requisitos bsicos: Debe ser rotulada con claridad y bien organizada, con secciones claramente indicadas, almacenarlas en carpetas e ndice. Los diagramas debern ser claros, no aglomerados y la escritura manuscrita deber ser legible . La documentacin deber ser completa. Se incluir una leyenda o explicacin de los trminos utilizados. La documentacin siempre se conserva actualizada. NORMALIZACIN Asegrese de que los estndares sean completos, actualizados, documentados y legibles. Auditar permanentemente para que se cumplan los estndares. Evaluar si los estndares establecidos son los requeridos y hacer los cambios necesarios para que dichos estndares sean los apropiados. TEORIA GENERAL DE LOS MANUALES DE DOCUMENTACIN Durante el desarrollo de un sistema, desde su concepcin hasta su puesta en marcha se ha generado gran cantidad de documentos, que en muchas ocasiones se han visto modificados por documentos posteriores debi do a cambios en el sistema. Para evitar confusiones en las revisiones de la documentacin se desarrollan diferentes tipos de documentos dirigidos a las personas que trabajarn con el sistema y para facilitar el mantenimiento del mismo. La documentacin de un sistema debe ser marcada adecuadamente, bien organizada actualizada y completa; todos los trminos utilizados deben explicarse. La documentacin se har disponible a todos los usuarios dc acuerdo a sus necesidades.

EL ESTILO DE REDACCIN DE LOS MANUALES DE DOCUMENTACIN DEBE SER: Concreto. Ser preciso y definir los trminos utilizados. Utilizar prrafos corto s. Utilizar ttulos y subttulos. Utilizar formas activas en lugar de pasivas. No emplear frases largas que presenten hechos distintos. No hacer referencia a una informacin solamente con el nmero de referencia 3. MANUAL ADMINISTRATIVO Sirve como punto de partida al Sistema propuesto, ya que ser funcin de la gerencia, de acuerdo con los usuarios de dicho Sistema, determinar silo expuesto en l satisface los requerimientos del propio sistema. Una vez lograda la aprobacin, se estar en condiciones de iniciar el desarrollo del Sistema propuest o e ir integrando el resto de la documentacin. El manual tiene como finalidad el permitir a la alta gerencia tener la informacin necesaria y suficiente sobre un sistema en p articular y servir como fuente dc consulta una vez que el Sistema ha sido implantado. Contenido Nombre del sistema Describir el nombre del sistema a implantar en la empresa. Equipo Encargado Del Sistema Nombre del personal encargado del anlisis y diseo del sistema. Resumen Administrativo Compendio de lo puntos que se describen en el manual, el cual tiene como propsito permitir a los altos ejecutivos enterarse en forma somera de la propuesta del sistema. En este punto aparece por primera vez el nombre del sistema, el cual deb e ser nico, este deber conservarse invariable en todos los documentos referentes a ese sistema. PLANTEAMIENTO Este punto tiene como finalidad registrar los antecedentes que servirn de partida al desarrollo del anlisis del sistema. Se debe mencionar: Dependencia que requiri el trabajo. Personas y / o puestos ocupados por estas al momento de req uerirse el trabajo (acuerdos, disposiciones legales, memorandos, y otros) Condiciones y criterios que normaron el desarrollo del trabajo. Fechas correspondientes. OBJETIVOS DEL SISTEMA Aqu se dejarn establecidos los objetivos que debe cubrir el sistema, en forma clara y precisa para evitar errores de interpretacin.

ENTRADAS DEL SISTEMA (INFORMACIN A CAPTAR) Debe quedar especificado en este punto, los documentos fuentes que inician las operaciones del sistema as como la informacin detallada de aquellos conceptos que sern los datos a captar por el sistema. Se debern mencionar todos los datos que en forma secundaria originan una entrada importante al sistema. Ejemplo: Nombre del Documento Fuente Mdulo o Procedimiento donde entra el documento Usuarios que manejan el Origen del documento documento

SALIDAS DEL SISTEMA (RESULTADOS A OBTENER) En este punto, solamente se describirn los resultados de mayor importancia obtenidos a travs de todo el proceso. En esta seccin se debe dar mayor nfasis a la informacin que el sistema proporciona cuidando de no hacer tan slo mencin de los resultados a obtener. Ejemplo: Nombre de la salida Destino Periodicidad en que se genera Usuarios que lo requieren

DIAGRAMACION GENERAL DEL SISTEMA Es la representacin grfica de las fases del Sistema y su flujo a travs de las dependencias que intervienen en el mismo, aunque en forma generalizada. La tcnica a utilizar y l a simbologa debe ser seleccionada por los interesados. EXPLICACIONES DE LAS FASES DEL SISTEMA Este punto se encuentra relacionado con el anterior ya que lo que se muestra grficamente, ahora se describe en forma genrica, explicando los procesos que se llevan a cabo en cada dependencia sin profundizar en detalles tcnicos o especfico s. Se deber resaltar aquellas fases del proceso en las cules se obtengan resultados de importancia as como aquellas que requieran una REQUERIMIENTOS DEL SISTEMA Se establecen los recursos, tanto humanos como materiales que son necesarios para poder llevar a cabo el sistema. Presentar costos y descripcin, adems de las cantidades que se requieran. ESTIMACIN DE LA FECHA PROBABLE DE IMPLEMENTACIN DEL SISTEMA Es necesario que exista una fecha probable de implantacin cuya base ser la terminacin de tod as las actividades para la creacin del sistema, tales como: anlisis, programacin, elaboracin de formas, y otros. Se recomienda utilizar diagrama de Grantt o de Pert para establecer el perodo de las actividades requeridas para el desarrollo del sistema. Ejemplo: Escala del tiempo en semanas Actividades a realizar Presentacin de la 1 ***** 2 3 4

Propuesta Anlisis Costo / Beneficio Adquisicin del Equipo Entrenamiento CONSIDERACIONES GENERALES DEL NUEVO SISTEMA En este punto se deber sealar las ventajas, desventajas, y principales diferencias del nuevo sistema con el anterior, tales cmo seguridad, disminucin de costo, ahorro de tiempo, flexibilidad, confiabilidad y otros. Adems, desarrollar en cualquier aspecto de la propuesta del sistema que no file considerado en el desarrollo de los puntos antes mencionados. 4. MANUAL DE USUARIO Expone los procesos que el usuario puede realizar con el sistema implantado. Para lograr esto, es necesario que se detallen todas y cada una de las caractersticas que tienen los programas y la forma de acceder e introducir informacin. Permite a los usuarios conocer el detalle de qu actividades ellos debern desarrollar para la cons ecucin de los objetivos del sistema. Rene la informacin, normas y documentacin necesaria para que el usuario conozca y utilice adecuadamente la aplicacin desarrollada. OBJETIVOS Que el usuario conozca cmo preparar los datos de entrada. Que el usuario aprenda a obtener los resultados y los datos de salida. Servir como manual de aprendizaje. Servir como manual de referencia. Definir las funciones que debe realizar el usuario. Informar al usuario de la respuesta a cada mensaje de error. PASOS A SEGUIR PARA DEFINIR COMO DESARROLLAR EL MANUAL DE USUARIO. Identificar los usuarios del sistema: personal que se relacionar con el sistema. Definir el diferente tipo de usuarios: se presentan los diferentes tipos de usuarios que usaran el sistema. Ejemplo: usuarios directos, indirectos. Definir los mdulos en que cada usuario participar: Se describen los mdulos o procesos que se ejecutarn por cada usuario en forma narrativa breve y clara. IMPORTANCIA DEL MANUAL DE USUARIO El Manual de Usuario facilita el conocimiento de:
y y y y

*****

***** *****

Los documentos a los que se pueden dar entrada por computadora. Los formatos de los documentos. Las operaciones que utiliza de entrada y salida de los datos. El orden del tratamiento de la computadora con los datos introducidos. El momento en que se debe solicitar una operacin deseada. Los resultados de las operaciones realizadas a partir de los datos introducidos.

Al elaborar el Manual de Usuario, hay que tener en cuenta a quin va dirigido es decir, el manual puede ser manejado desde el director de la empresa hasta el introductor de datos. Por consiguiente, debe redactarse de forma clara y sencilla para que lo entienda cualquier tip o de usuario. CONTENIDO

DIAGRAMA GENERAL DEL SISTEMA Muestra en forma condensada el flujo general de la informacin y de las actividades que se realizan en el sistema. Proporciona una visin general del sistema. Representar los diagramas utilizando para el lo diagramas de bloques.

DIAGRAMA PARTICULAR DETALLADO. Presentar grficamente todos los pasos que se efecten dentro del departamento usuario a quien est dirigido este manual. Deben especificarse los archivos de entrada, salida, los resultados, revisiones y procesos manuales. EXPLICACIN GENRICA DE LAS FASES DEL SISTEMA En este punto se explica en forma especfica y detallada todas las o peraciones que aparecen representadas en forma grfica en el diagrama particular. Se analizan cada una de las fases sealando: El proceso principal que se desarrolla. La entrada de la informacin. La obtencin de un resultado parcial. El envo de informacin a otra dependencia. INSTALACIN DEL SISTEMA La instalacin del sistema proporciona detalles completos sobre la forma de instalar el sistema en un ambiente particular. INICIACIN AL USO DEL SISTEMA En este punto se explica cmo iniciarse en el sistema y cmo se pueden utilizar sus cualidades comunes. Esta documentacin debe decir al usuario cmo salir de un problema cuando las cosas funcionan mal. MANUAL DE REFERENCIA Es el documento definitivo de cara al usuario y debe ser completo. Describe con detalle las cualidades del sistema y su uso, los informes de error generados y las situaciones en que surgen esos errores. Dependiendo del sistema, los documentos al usuario se pueden proporcionar por separado o reunidos en varios volmenes. Los sistemas de ayuda en lnea evitan que el usuario pierda tiempo en consultas manuales. CADUCIDAD DE DOCUMENTO FUENTE Y DESTINO FINAL Como el usuario trabajar con documentos fuentes, stos podrn tener un perodo de retencin y un destino especificado. 5. MANUAL DE CAPTACIN Permite tener una clara visin del proceso de Captacin de las latas fuentes previo al procesamiento electrnico de los mismos. OBJETIVOS Documentar al usuario a cerca del recorrido a travs de las pantallas del sistema.

Conocer la forma cmo el usuario puede utilizar el equipo necesario para la ejecucin del sistema. Contenido DIAGRAMA GENERAL DEL SISTEMA Este diagrama debe ser presentado grficamente y en forma sencilla. Representar los diagramas utilizando para ello diagramas de bloques ( es el mismo diagrama que se presenta en el Manual Administrativo). DIAGRAMAS DE PANTALLA Presentar en este punto el flujo del sistema en las pantallas utilizadas por cada mdulo. PUNTOS A DOCUMENTAR EN UNA PANTALLA: Explicacin del recorrido para llegar a la pantalla. Formato de los datos a captar. Formato en que son captados los datos. Explicacin Genrica De Las Fase s Del Sistema Es una explicacin clara, breve de todos los mdulos que se presentan en el diagrama general. Equipo Utilizado Para La Captacin Se debe crear un instructivo que permita al usuario el entrenamiento del sistema. DEBE CONTENER LOS SIGUIENTES PUNTOS: USO DEL EQUIPO: Describir detalladamente el uso correcto del equipo utilizado para la captacin de la informacin, dando una explicacin del encendido, manejo, control y del material que se usa como medio de captacin de los datos. Entrenamiento del Software de la aplicacin: Explicacin del software utilizado en complemento al sistema. Ejemplo: como entrar y salir del sistema. Situaciones Anormales Se presentan mensajes que se emiten al momento de la captura de los datos o cualquier con dicin fuera dc lo normal. Ejemplo: Situacin anormal Mensaje ENTREGAS AL COMPUTADOR Establecer un calendario con fechas de entrega al computador, al igual que un horario para la obtencin de resultados. El calendario determina marca cundo las actividades deben llevarse a cabo dc manera que la gestin del sistema no se vea afectado. Si es un sistema en lnea no se requiere. Ejemplo: Operacin Solicitud de reporte Frecuencia Semanal Objetivo Hora de Entrada Hora de salida 3:00 p.m. Causas Soluciones

Actualizar informe Antes de las 2:00 p.m. del departamento X

Mensual Caducidad De Documentos Fuentes Establecer por escrito la fecha de caducidad de los documentos fuentes, el fin a que han de destinarse ya sea para su destruccin, devolucin o conservacin en un archivo. MANUAL DE OPERACIN Objetivo Contiene la informacin que permite al personal de operacin utilizar en forma eficiente la operacin de los sistemas de procesamiento electrnico. Contenido DIAGRAMA GENERAL DEL SISTEMA Este diagrama debe ser presentado grficamente y en forma sencilla. Representar los diagramas utilizando para ello diagramas de bloques (es el mismo diagrama que se presenta en el Manual Administrativo ). DIAGRAMA GENERAL DEL FLUJO DEL PROCESO ELECTRNICO. Se representa en este diagrama todo el ambiente perifrico que interacta en el sistema en cuanto a: entradas manuales, medios magnticos y dispositivos de salida. La simbologa a utilizar debe ser establecida como estndar. (Ejemplos: cintas, discos, disquetes). EXPLICACIN GENRICA DE LAS FASES DEL SISTEMA Es una explicacin clara, breve de todos los mdulos que se presentan en el Diagrama general descrito anteriormente. Diagrama De Pantallas Del Sistema Se presenta en este punto el flujo del sistema en las pantallas utilizadas por cada mdulo. Puntos a documentar en una pantalla: Explicacin del recorrido en pantalla. Formato en que son captados los datos. Instruciwo De Operacin Por Programa Se debe desarrollar por cada programa dcl sistema. Incluye: Diagrama electrnico del pr ograma. NO DEJE QUE LO URGENTE NO DEJE TIEMPO PARA LO IMPORTANTE Por: Pablo Antonio Ortiz Nez La parbola de la rana que se cocina Recordemos esta famosa parbola. Sabe como se cocina a una rana? Se coloca la rana en una olla a temperatura ambiente y se enciende el fogn; en este momento la rana nada tranquilamente; el agua comienza a calentarse lentamente y la rana sigue nadando tranquilamente y no escapa pudindolo hacer; el agua continua calentndose hasta que la rana se convierte en un suculento pl ato. Parece que los humanos estamos diseados genticamente para actuar frente a las crisis y no para actuar para construir la realidad que deseamos; esta programacin, de acuerdo con la teora de la evolucin, se debe a que a nuestros caverncolas antepa sados les era ms importante para su supervivencia el huir ante la amenaza de una fiera que concebir un futuro posible para l y sus descendientes. La compleja sociedad

interdependiente en que vivimos nos exige aptitudes precisamente opuestas, pero an no nos hemos adaptado a esta nueva realidad. A mi modo de ver ciertas prcticas en el desarrollo de software no se hacen cuando se deben hacer y pagamos muy caro por ello. Me refiero aqu a la documentacin, la garanta de la calidad del software, la planeacin y el anlisis de riesgos. En todos estos casos encontramos el mismo patrn de la rana que se hierve. Nos volvemos adictos a las soluciones temporales Quiero explicar aqu un arquetipo sistmico conocido como desplazamiento de la carga. Consiste en que un sistema se vuelve adicto a las soluciones sintomticas y con ello se posponen las soluciones fundamentales mientras tanto el sistema se va degradando paulatinamente en su capacidad de resolver el problema. Este arquetipo se representa mediante ciclos de realimentacin positiva, negativa y retardos mediante la siguiente plantilla: Solucin Fundamental Retardo Sntoma del Problema Solucin Sintomtica (temporal) Aptitud del Sistema para Aplicar solucin Fundamental (Efecto Colateral) Todos los Derechos Reservados 2003 por Pablo Antonio Ortiz. Pgina 1 de 1 Asociacin Antioquea de Ingeniera Informtica Este grfico se debe leer as: Entre ms se presente el sntoma del problema, ms necesidad hay de aplicar la solucin sintomtica y esto hace que se retarde la aplicacin de la solucin fundamental. Hay un resultado colateral y es que se degrada la aptitud del sistema para aplicar la solucin fundamental. Es exactamente la misma situacin que se presenta cuando una madre interviene en los problemas de relacin de su hijo con otros nios; pero con ello lo nico que logra es que su hijo cada vez sea menos capaz de manejar sus relaciones. En algunas situaciones del desarrollo de software encontramos el mismo patrn. Utilizaremos esta plantilla para ilustra r algunos problemas que se presentan en el desarrollo de software. La documentacin La documentacin de todas las clases como la de instalacin del software, la del desarrollo del software, la del usuario final, los comentarios en el cdigo fuente y la do cumentacin en lnea, muchas veces se deja para lo ltimo por lo cual se hace mal o simplemente no se realiza. El programador est tremendamente interesado en mostrar un producto funcional porque es lo que valora inmediatamente el cliente descuidando la do cumentacin. Un buen manual del usuario luego nos va ahorrar tremendos costos de soporte; unos manuales de desarrollo del sistema actualizados donde se consigna la arquitectura del software, luego nos va ahorrar costos en el mantenimiento del producto. Sin embargo en el momento de desarrollo del software la premura de mostrar el producto operacional soslaya la importancia de la documentacin. El arquetipo sistmico de desplazamiento de la carga para esta situacin se representa as: Levantar y actualizar la documentacin del software Retardo Hay que realizar los cambios rpidamente porque el cliente presiona Parchar el cdigo fuente La arquitectura del software y su correspondiente documentacin se degrada

Todos los Derechos Reservados 2003 por Pablo A ntonio Ortiz. Pgina 2 de 2 Asociacin Antioquea de Ingeniera Informtica El aseguramiento de la calidad del software Cmo se retrasan los proyectos ? Diariamente. Creemos que no es posible establecer la calidad del programa que estamos construyendo hasta que no tenemos el producto terminado. Nada ms errado. Si definimos entregables durante todo el ciclo de desarrollo del software como diagramas de clases, diseo de la interfaz del programa, implementacin de clases, diseo de casos de pruebas, es posible establecer si el producto que estamos construyendo es de calidad an en sus etapas iniciales. Las revisiones tcnicas formales, RTF es una tcnica muy efectiva; si hemos realizado una cuidadosa planificacin del trabajo a realizar y se han asignado responsabilidades y establecidos unos resultados de cada actividad es posible realizar revisiones por personas diferentes al diseador del producto. El encargado de realiz ar un subproducto lo entrega a un coordinador de la reunin; este subproducto debe ser entregado a los revisores con antelacin a la reunin de revisin para que todos los participantes vengan preparados y se optimice el tiempo; estos revisores con un crit erio profesional lo evalan. El subproducto es aceptado, rechazado o aceptado con ciertas modificaciones. Por qu no hacemos lo anterior? Algunos dicen que no tenemos la cultura de la calidad, que hacemos software artsticamente sin ningn tipo de mtodo, otros dicen que no hay recursos para asignar a las revisiones y que esto sobrecarga el proceso de desarrollo innecesariamente. El arquetipo sistmico de desplazamiento de la carga para esta situacin es el siguiente: Aplicar revisiones tcnicas formales durante todo el desarrollo del proyecto Retardo No hay tiempo ni personal para realizar revisiones Continuar con el desarrollo sin revisiones La calidad del Software se va deteriorando La Planeacin y el Anlisis de Riesgos Entre ms rpido empiece a esc ribir cdigo, ms tardar en terminarlo. Una vez a un programador se le pidi que desarrollara un sistema por Internet para recepcin y seguimiento de pedidos de los clientes. El jefe le pregunt al programador que cuando lo teminara; el programador, desp us de realizar un estudio, le dijo que el producto era ms fcil de construir de los que pensaba y que lo tendra listo en cuatro meses. A los 2 meses lo llama el jefe y le pregunta como va el proyecto; el programador entusiasmado le dice que lleva el 50% del producto y que la tendr listo para la fecha lmite. A los 4 meses el jefe lo llama y le pregunta como va y el programador dice he encontrado unos problemas pero lo solucionar rpidamente para entregar el producto y cuanto llevas?, replic el je fe, el programador respondi el 90%; un mes despus de la fecha lmite el programador aun estaba en el 90%.y dos meses despus continuaba en el 90%! Finalmente el programador logr terminar el producto en el doble de tiempo de lo previsto. Esta historia no es ms que la ejemplificacin de la famosa regla 90 -90 El primer 90% de un sistema se lleva el 10% del tiempo y esfuerzo invertido el ltimo 10% se lleva el 90% del tiempo y esfuerzo Por qu ocurre todo esto? Por qu parece que los proyectos de des arrollo de software son interminables? Yo pienso que buena parte se debe a que no realizamos una buena planeacin, no hacemos un cuidadoso anlisis de requisitos; dentro de la planeacin, una consideracin importante son los riesgos. Por anlisis de riesgos entendemos el analizar que puede salir mal durante el desarrollo del proyecto y plantear estrategias para reducir y controlar el riesgo. Con una buena planeacin y anlisis de riesgos, incluso podramos evitar emprender proyectos que no tienen una base s lida y viable para su construccin. El problema de tener apoyado la escalera en pared equivocada.

Pero porqu no hacemos una cuidadosa planeacin y anlisis de riesgos? Algunos dicen que para que gastar tiempo en tareas tan ftiles; otros dicen, vamos d irectamente al asunto de la programacin que es lo realmente importante; otros dicen, para qu sobrecargar intilmente el proyecto con ms tareas y actividades? El arquetipo sistmico de desplazamiento de la carga para esta situacin es el siguiente: Surgen problemas no previstos y nos atrasamos en la agenda del proyecto El proyecto de desarrollo de software se va empantanando Actuar sobre los problemas que tenemos Retardo Invertir tiempo en la planeacin, anlisis de requerimientos y anlisis de riesgo s Que hacer? Aplicamos las soluciones temporales porque al igual que en una adiccin, reducen el dolor o soluciona temporalmente una situacin. Lo que hay que hacer es tener coraje y una profunda conviccin de hacer las cosas bien y como se deben de una vez sin postergarlas. En el caso de la documentacin hay que hacerla a tiempo mientras se desarrolla el software; en el caso del aseguramiento de la calidad del software hay que realizar los controles continuamente durante todo el proyecto; en el caso de la planeacin y anlisis del riesgo debe ser un proceso de ajuste continuo durante todo el proyecto. En todos estos casos la organizacin de desarrollo de software y los programadores debemos pagar el precio que sea necesario para hacer las cosas bien hechas de una vez, esto se traduce en incremento de la agenda del proyecto vista desde el corto plazo, pero en definitiva un ahorro en tiempo y problemas futuros. Al igual que en las soluciones al problema del alcoholismo, podemos aplicar las soluciones si ntomticas slo para ganar tiempo para aplicar la solucin fundamental. Por ejemplo, si debemos realizar un cambio a un programa y no contamos con la documentacin y el cliente no da espera hay que hacer el parche en el programa pero no olvidar que el tr abajo interesante por realizar es el de levantar y actualizar la documentacin de software para que los futuros mantenimientos sean ms fciles de realizar. Muchas empresas de desarrollo de software, por problemas como los anteriores, estn en una olla con el agua calentndose, Ser que podrn saltar de ella . Organizacin general La descripcin de la solucin adoptada para la realizacin de un sistema propuesto puede hacerse de formas muy variadas. La finalidad de este documento es proponer una forma simp le de abordar ese Problema para que sea usada en la presentacin de prcticas de laboratorio en las que se exija la implementacin de una solucin completa. Estas normas debern entenderse como un mnimo orientativo en la organizacin de dicha documentaci n. La documentacin de un sistema deber dividirse en las siguientes partes: Documentacin de construccin. ndice de contenido. Especificacin. Arquitectura. Mdulos de nivel 1. Mdulos de nivel 2. ... Mdulos de nivel n. Documentacin de uso. Manual del usuario.

Configuracin del sistema. Documentacin complementaria. Restricciones del ambiente operativo de ejecucin. Ejemplos de test, salidas tpicas, etc. Errores. Bibliografa utilizada . Documentacin relativa al cdigo. Documentacin sobre la organizacin del cdigo. Cdigo fuente. Documentacin de construccin
y ndice de contenido Es una tabla que contiene las pginas de comienzo de cada una de las partes que siguen. y Especificacin Una descripcin de lo que debe hacer el sistema, idealmente sin entrar en cmo va a hacerlo. y Arquitectura Debe describirse qu particin del problema se ha realizado indicando qu mdulos se han usado, qu misin realiza cada uno y qu relaciones hay entre ellos. y Mdulos de un nivel cualquiera Habr una serie de mdulos de primer nivel, cada uno de los cuales se subdividir en otros mdulos de segundo nivel y as sucesivamente hasta completar el sistema.

En cada mdulo deber describirse su utilidad global, los servicios pblic os que presta y qu mdulos los utilizan. Igualmente si ciertos servicios del mdulo se prestan mediante la peticin de Servicios a mdulos de nivel inferior, deber decirse qu mdulos son utilizados por el que estamos documentando. Normalmente un mdul o subordinado estar construido en torno a la implementacin de los servicios de uno o varios tipos abstractos de datos de inters para la aplicacin. Es frecuente realizar el mdulo de nivel ms alto como un mdulo de control que solicita los servicios d e ms alto nivel a otros mdulos subordinados, en los que delega para realizar el trabajo de otros niveles inferiores. Incluso esa estrategia es aplicable a los mdulos de niveles ms bajos, pero deber evitarse acoplamientos entre mdulos en los que algun os mdulos de nivel bajo pidan servicios a mdulos de nivel superior. Para describir las funciones que componen un mdulo se separarn las descripciones de las funciones pertenecientes al interfaz pblico de las dems. Cada funcin se documentar indicand o su finalidad. Se especificar su prototipo y se comentar la semntica, el formato y el uso de cada uno de los argumentos y del resultado, indicando asimismo las restricciones de uso si la implementacin depende del sistema operativo. Documentacin de uso Manual del usuario Se documentarn en esta seccin las formas de uso del sistema a travs del interfaz de usuario o de comunicaciones que se haya previsto, poniendo ejemplos de uso legal y su salida tpica.

y Configuracin del sistema Se comentar aqu el conjunto de valores de las constantes de configuracin que el sistema asumir por defecto, indicando sus significados y sealando las formas de hacer los cambios que puedan necesitarse.

Documentacin complementaria Restricciones del ambiente operativo de ejecucin En esta seccin deben comentarse las particularidades que nuestro sistema necesite para ser ejecutado como servicios del sistema operativo o de comunicaciones que se usan de modo explcito y que podran afectar a la portabilidad del cdigo, et c. Ejemplos de test, salidas tpicas, etc. Incluiremos aqu una serie de ejemplos de salidas proporcionadas por el sistema en condiciones normales de uso.

Errores Se documentarn en esta seccin los errores detectados por el sistema, sus correspondientes mensajes de error, su significado y si son recuperables o no, indicando el procedimiento de recuperacin si lo hay.
Bibliografa utilizada Se documentar aqu la bibliografa usada para el diseo e implementacin del sistema. Documentacin relativa al cdigo Documentacin sobre la organizacin del cdigo Se indicar aqu la estructuracin de los archivos que componen el cdigo en los directorios correspondientes y toda la informacin necesaria para compilar y enlazar los distintos mdulos que se hayan u sado, tanto los implementados directamente por el desarrollador como los archivos objeto y las bibliotecas no estndares que deban utilizarse. Cdigo fuente Por ltimo se acompaar un listado organizado por mdulos del sistema objeto del trabajo, junto a los archivos auxiliares necesarios para su instalacin, configuracin, compilacin, enlace y ejecucin. Normas de presentacin En todo caso se entregar toda la documentacin y el cdigo en formato electrnico (el cdigo en formato ASCII y la documentaci n suplementaria en formato procesable mediante WORD 6.0 para Windows) y en formato impreso (tamao DIN A4 por una sola cara). Solamente en el caso en que as se establezca explcitamente por la longitud Excesiva del cdigo generado, se admitir que se presente la documentacin generalen ambos formatos (electrnico e impreso) y el cdigo solamente en formato electrnico DOCUMENTACION DE SISTEMAS. Los turbulentos cambios que vivimos en las realidades de cada negocio, imprimen una violenta velocidad a la construccin y modificacin de sus sistemas. Esto produce debilidades en los diseos, testeos, implementaciones y documentacin. Estas ausencias o pobrezas de documentacin slo son detectadas cuando necesitamos saber algo y la persona que lo hizo ya no est....o, cuando por temas regulatorios (principalmente en la industria financiera - Ver Comunicacin "A"-4609 del BCRA, apartado 3.1.4.), esta documentacin resulta obligatoria y est llegando una inspeccin a nuestras puertas. Ni qu hablar cuando estamos "esclavos" de las personas que conocen dnde tocar el sistema y slo ellas nos pueden ayudar...

Nuestro ofrecimiento es documentarle el sistema o partes que necesite, el tipo de documentacin que Ud. requiera , con una mnima atencin del personal a su cargo, para minimizar atrasos en los proyectos que est llevando a cabo. Algunos ejemplos de documentaciones a construir: 1. "Carpeta del proyecto": es el lugar donde deberan existir las distintas versiones de planes del proyecto, anlisis de alternativas y sus antecedentes o criterios de formacin de decisiones, intervenciones de las oficinas de legales e impositivas con sus requerimientos y alertas tempranas de cuidados a considerar, cambios de alcances al proyecto, pedidos de cotizacin u rdenes de compra involucradas en el proyecto, planes de construccin, "saltos" autorizados de estndares de construccin de programas, anlisis de cap acidad de disco, canales de comunicacin, casos de prueba, resultados esperados, plan de implementacin, etc. etc. "Carpeta del sistema": con su correspondiente lista de eventos, diagrama de contexto, modelo de usuarios, diagramas de entidad - relacin, modelo de implementacin, modelo y diccionario de datos, diagrama de flujo, dilogos de pantallas, diseos de archivos, pantallas y reportes, nmina de controles. "Manual del usuario": donde claramente quien opera el sistema, ya sea como i ngresante de datos, autorizante o lector de reportes, sabr cmo manejarse frente a su mquina y reportes. "Carpeta de carga de mquina": indicando especficamente la ventana de procesamiento donde debe ser incluido el proceso, tiempos estimados d e duracin, acciones en caso de fallas, bibliotecas intervinientes, ..etc... "Instrucciones de operacin": donde el operador del computador recibe claramente la identificacin de qu soportes magnticos debe usar, qu debe contestar ante eventuale s mensajes del sistema aplicativo o del sistema operativo, usuarios a consultar o equipos de emergencia para casos de fallas, es decir todo aquello que le permita manejar al sistema. "Instrucciones de distribucin de salidas": para saber cuntas c opias imprimir, qu tipo de papel o formulario debe utilizarse, cmo debe setearse la impresora, a quin debe dirigirse cada copia, qu controles deben realizrsele antes de distribuir, cul es la caracterstica de confidencialidad o no de la informacin c ontenida en los reportes, tamaos promedio de los mismos para evitar impresiones innecesarias, controles de calidad previos a su impresin total final, etc.

2.

3.

4.

5.

6.

Adicionalmente, si as Ud. lo desea, ante eventuales modificaciones, estaremos en condiciones de actualizar su documentacin con el simple envo de su parte, de los cambios que hubiera implementado en el sistema en cuestin. Inicialmente le entregaremos un ejemplo de una carpeta y Ud. nos dir si est de acuerdo o no con dicho modelo y qu cosas desea eventualmente modificar o agregar. Si desea que nuestro personal se ponga en contacto con usted para ofrecerle una cotizacin sin cargo sobre la resolucin de su problema, haga clic aqu