CAPITULO 1. Estructura del Sistema de Documentacin 1.

Introduccin Producir una buena documentacin no es fcil ni barato; el proceso es tan difcil como producir un buen software. La elaboracin de la documentacin es un proceso esencial para poder garantizar la calidad del software, lo cual requiere una adecuada asignacin de recursos financieros, materiales, humanos y de tiempo, o sea, la calidad del proceso de elaboracin de la documentacin se traduce en calidad del software. De la efectividad de la documentacin depende en gran medida el xito de los proyectos de sistemas o productos de software. La documentacin comienza con el inicio del proyecto y contina a lo largo de todo el proceso de desarrollo del software: durante la planificacin preliminar y factibilidad del proyecto, el anlisis detallado, el diseo preliminar (general), el diseo detallado, la programacin, las pruebas, la implantacin, el uso y el mantenimiento del software. El proceso de documentacin no termina hasta que el producto de software haya llegado al final de su vida til, y an as, la documentacin del proyecto de un producto de software descontinuado sirve de referencia histrico-estadstico para el desarrollo de otros proyectos. Por tanto, la documentacin constituye un proceso integral del proceso de desarrollo del software, ya que es requerida en cada etapa del ciclo de vida y por eso requiere estar disponible y ser mantenida en cada uno de los momentos del proceso, en los cuales la documentacin juega un papel vital. Los procesos que documentacin debern estar integrados en los procesos de desarrollo del software de acuerdo con el modelo de referencia del ciclo de vida seleccionado en una organizacin productora de software. La documentacin es esencial, tanto para soportar el producto de software, para los procesos del desarrollo del software, como para la administracin del proyecto. Por ello cada tipo de documentacin est destinada para diferentes lectores: administradores o jefes de proyecto, analistas, diseadores, programadores, especialistas en aseguramiento de la calidad del software, auditores informticos, programadores de mantenimiento, especialistas en publicidad y usuarios de diferentes profesiones y niveles no expertos en informtica. El grado de detalle, enfoque, contenido, estructura y presentacin de los diferentes documentos varia de un tipo de documento a otro y de un tipo de proyecto de software a otro. La documentacin se producir y mantendr en conformidad con las normas, prcticas y convenciones establecidas al efecto y de acuerdo con los trminos del contrato de los proyectos de software en los cuales, adems de los requerimientos del software, se especifican los requerimientos de la documentacin. 2. Trminos y definiciones Para el propsito de este sistema de documentacin, se utilizarn los trminos y definiciones de: ISO 2382:1976-1992 Information technology - Vocabulary Part 1-Part 25.

 ANSIIIEEE Std 729-1983 IEEE Standard Glossary of Software Engineering Terminology NC 59-08 VEN Procesamiento automatizado de la informacin 3. Campo de aplicacin del sistema de documentacin El sistema de documentacin del software est dirigido a los administradores, profesores, investigadores, desarrolladores, comercializadores, usuarios y clientes del software. Su campo de aplicacin es el desarrollo y mantenimiento de la documentacin del software. Este sistema de documentacin: a) Es aplicable a todo tipo de software (software de sistema y software de aplicacin), independientemente del tamao y del nivel de complejidad (un sistema mono o multinivel, un subsistema o un elemento componente del software); b) Abarca todos los diferentes tipos de documentacin que se generan durante todo el proceso de desarrollo de los proyectos de productos, de software, independientemente del modelo del ciclo de vida seleccionado como el ms apropiado para cada organizacin (clsico, de prototipo, una combinacin de ambos u otro) entre el nmero de modelos de referencia de ciclo de vida existentes; c) Es vlido para cualquier divisin en etapas que se haga al proceso de desarrollo del software, debido a que en este trabajo solamente hace referencia a los documentos que se elaboran como resultado de la ejecucin de las diferentes tareas o actividades durante los diferentes momentos del desarrollo de los proyectos de software; d) Es independiente de los mtodos, tcnicas y herramientas Manuales y/o automatizados que se empleen para la produccin del software y de su documentacin durante cada uno de los procesos de desarrollo de los proyectos de software, as como de la metodologa de desarrollo que se utilice (orientada a las estructuras o a objetos); pero si requiere y presupone la utilizacin de una metodologa de desarrollo para la ingeniero del software; e) Es independiente del uso del software (general o especifico) y del tipo de ambiente de procesamiento (en lote o interactivo, en tiempo real o compartido, en lnea o distribuido), as como de sistemas mono o multiusuario; f) Es independiente de los medios y mtodos utilizados para la interconexin, comunicacin y transferencia de informacin, en el caso de ambiente de comunicacin del procesamiento distribuido; g) Es independiente tambin del ambiente del producto de software en cuanto al software de sistema y al hardware (macro, mini, microcomputadora); h) Presupone la presencia de actividades tales como el aseguramiento de la calidad, la auditora informtica, la proteccin y seguridad de la informacin, la administracin de proyectos y la administracin de la configuracin del software; i) Presupone tambin la produccin, distribucin, promocin y comercializacin de los productos de software en los diferentes tipos de mercados, as como la presencia de relaciones contractuales de las operaciones de compra-venta del software por medio de contratos o convenios.

El usuario de este sistema de documentacin es responsable de: a) Seleccionar el modelo del ciclo de vida del software ms apropiado para el desarrollo del proyecto de software en cuestin en base a sus caractersticas particulares y a los requerimientos contractuales referentes a la documentacin del software; b) Seleccionar y aplicar los mtodos de desarrollo del software de acuerdo con la metodologa de desarrollo seleccionada y de ejecutar las actividades apropiadas de los diferentes procesos de desarrollo del proyecto; c) Seleccionar los documentos establecidos en la metodologa de desarrollo escogida, ajustndose a los documentos que se establecen en este sistema de documentacin del software. 4. Objetivos del sistema de documentacin Los objetivos del sistema de documentacin del software son: a) Establecer los requerimientos del desarrollo y mantenimiento de la documentacin del software; b) Obtener el consenso necesario de las partes que intervienen en el desarrollo del proyecto de software; c) Ayudar a la confeccin de una documentacin planificada y normalizada; d) Permitir que el proceso de confeccin de la documentacin del software se realice como un proceso integral paralelo a las etapas del proceso de desarrollo del software; e) Lograr una documentacin del software con la calidad requerida para satisfacer las necesidades del usuario; f) Permitir la correcta promocin y comercializacin del software. 5. Ventajas del sistema de documentacin La documentacin que se produzca utilizando este sistema de documentacin: a) Permitir al personal de direccin del proyecto ejercer un control efectivo sobre el proceso de desarrollo, ya que podrn ms fcilmente realizar la estimacin del tiempo y los recursos requeridos para la ejecucin del proyecto; b) Facilitar la toma de decisiones durante el trabajo de desarrollo del software y la minimizacin del personal que interviene; c) Facilitar el intercambio de informacin entre las partes involucradas, trayendo como consecuencias una seleccin de objetivos que puedan ser fcilmente alcanzados por el software y un diseo funcional ms completo y mejor concebido; d) Permitir a la administracin ejercer el control sobre el proceso de desarrollo de los proyectos de software;

e) Permitir a los usuarios del software utilizarlo correcta y eficientemente; f) Ayudar a los operadores de computadoras a ejecutar el software; g) Ayudar al diagnstico y correccin de los errores y fallos; h) Brindar la informacin sobre el software corno ayuda para el mantenimiento del software y de su documentacin; i) Permitir que otros equipos de proyectos tomen experiencia del trabajo desarrollado en otros proyectos similares 6. Estructura organizativa del sistema de documentacin El sistema de documentacin del software est conformado estructuralmente por 11 partes componentes como se muestra en la figura 1. Estructura del sistema de documentacin: establece aspectos generales de la documentacin del software, los trminos y definiciones utilizados, el campo de aplicacin del sistema de documentacin del software, sus objetivos, las ventajas que ofrece, su estructura organizativa funcional y las relaciones con otros sistemas. Administracin de la documentacin: establece los lineamientos generales necesarios para guiar a los administradores (personal de direccin y jefes de proyectos) de la actividad de informtica en las organizaciones con funciones de investigacin, produccin y comercializacin del software o de productos basados en software, los cuales son los responsables de producir la documentacin del software con la calidad requerida. Tipos de documentos: establece los tipos de documentos que se producen durante los diferentes procesos del desarrollo de los proyectos de software, as como sus interrelaciones. Estructura general y formato de los documentos: establece la estructura general y el formato de los documentos que conforman la documentacin de los proyectos de software. Estudio, anlisis o investigacin preliminar: establece la estructura y el contenido de los elementos especficos de los documentos que se producen para dar inicio a un proyecto y proceder al estudio, anlisis o investigacin preliminar y como resultado de realizar las actividades de concepcin, planificacin y fundamentacin de la factibilidad del proyecto de software. Anlisis detallado (requerimientos del software): establece la estructura y el contenido de los elementos especficos de los documentos que se producen para dar inicio al anlisis detallado de la variante seleccionada para el diseo del software y como resultado de realizar las actividades de anlisis, determinacin y especificacin de los requerimientos del software. Diseo general y detallado: establece la estructura y el contenido de los elementos especficos de los documentos que se producen como resultado de realizar las actividades del diseo(preliminar o general del sistema y detallado de sus elementos componentes), as como las actividades de planificacin de las pruebas de aceptacin y de la implantacin. ESTRUCTURA ORGANIZATIVA-FUNCIONAL

SISTEMAS DE DOCUMENTACIN DEL SOFTWARE Desarrollo de la programacin, pruebas, depuracin y soporte de software: establece la estructura y el contenido de los elementos especficos de los documentos que se producen como resultado de realizar las actividades del desarrollo de la programacin, de las pruebas (de unidad de los programas, integracin de subsistemas y del sistema), de la depuracin de los errores durante la puesta a punto de los programas y de la elaboracin de los manuales de soporte del software. Pruebas de aceptacin e implantacin: establece la estructura y el contenido de los elementos especficos de los documentos que se producen como resultado de realizar las actividades relacionadas con la ejecucin de las pruebas de aceptacin del productor y del usuario y con la implantacin del software. Operacin y mantenimiento: establecer la estructura y el contenido de los elementos especficos de los documentos que se producen como resultado de realizar las actividades relacionadas con la operacin y el mantenimiento del software. Registro, almacenamiento, manipulacin, reproduccin y distribucin: establece los lineamientos generales para registro, el almacenamiento, la manipulacin, la reproduccin y la distribucin de los documentos que conforman la documentacin de los proyectos de software. 7. Relaciones con otros sistemas El sistema de documentacin del software establece relaciones con otros sistemas, los cuales complementan la informacin requerida para el desarrollo de una documentacin con calidad. (figura2). a) Ingeniera del software. Se refieren fundamentalmente a los lineamientos metodolgicos sobre: Seleccin del modelo de referencia del ciclo de vida del software; Clases de metodologas; Actividades de los procesos de desarrollo del software; Administracin de proyectos de software; Mtodos, tcnicas y herramientas. b) Comercializacin del software. Se refieren fundamentalmente a los lineamientos metodolgicos sobre: Relaciones contractuales de compra-venta (contratos de desarrollo de proyectos, de servicio de procesamiento, de licencia de utilizacin, de mantenimiento, garanta de mantenimiento y garanta de calidad); Actividades de los procesos de pre-venta, venta y post-venta.

Figura2 c) Aseguramiento de la calidad del software. Se refieren fundamentalmente a los lineamientos metodolgicos sobre: Requerimientos de la calidad de la documentacin del software; Administracin de la configuracin del software. d) Auditora informtica. Se refieren fundamentalmente a las regulaciones establecidas por la auditoria informtica para posibilitar que los sistemas puedan ser auditados. e) Proteccin y seguridad. Se refieren fundamentalmente a los patrones estndares que regulan, por ejemplo, el control del acceso no autorizado. f) Vocabulario (trminos y definiciones). Se refieren fundamentalmente al vocabulario tcnico uniforme a utilizar sobre: Trminos fundamentales; Ingeniera del software; Organizacin de datos; Representacin de datos; Control, integridad y seguridad; Confiabilidad, mantenimiento y disponibilidad; Especficos de la actividad objeto de investigacin (ejemplo: grficos de computadoras, programacin, publicacin asistida por computadora, etc.). g) Simbologa. Se refieren fundamentalmente a las notaciones que se utilizan para las diferentes representaciones de la informacin, como por ejemplo en los diagramas. h) Actividad objeto de investigacin. Se refieren fundamentalmente a aquellas normas que se relacionan directamente con la actividad que se investiga para su automatizacin, como por ejemplo las de base de datos para la elaboracin de un Sistema de Gestin de Base de Datos, las relaciones con la actividad militar en un sistema de ese tipo, etc. i) Otros. Se refieren fundamentalmente a todas aquellas normas que se relacionan indirectamente con la actividad objeto de investigacin, pero que son necesarias observar como, por ejemplo, las relaciones con el intercambio de informacin, los tipos de caracteres, etc.

CAPITULO 2. Administracin de Documentacin Este capitulo establece los lineamientos generales necesarios para guiar a los administradores (personal de direccin y jefes de proyectos) de la actividad de informtica en las organizaciones con funciones de investigacin, produccin y comercializacin del software o de productos basados en software, los cuales son los responsables de producir y mantener actualizada la documentacin del software con la calidad requerida. Orienta la poltica, las normas, los procedimientos, los recursos y los planes por los cuales tienen que preocuparse los administradores con el objetivo de administrar de forma efectiva la documentacin del software. Tambin hace referencia a las normas que pueden ser utilizadas para desarrollar las normas propias de cada organizacin. Proporciona una estructura sobre la cual puede ser construido una base slida para lograr una administracin efectiva del proceso de desarrollo y mantenimiento de la documentacin del software, el cual constituye un proceso integral critico dentro del proceso de desarrollo del software. El desarrollo y el mantenimiento de la documentacin del software constituyen un esfuerzo necesario y continuo desde el comienzo del software hasta su distribucin. La documentacin cubre completamente el ciclo de vida del software, es requerida para todas las etapas. Comienza con la solicitud del inicio de un proyecto de software y contina con el anlisis, el diseo, la programacin, la prueba, la implantacin, el uso y el mantenimiento del software. El proceso de documentacin puede ser considerado que ha finalizado solamente cuando el software llega al final de su vida til. La documentacin es esencial para el xito de cualquier proyecto de desarrollo de software, si la documentacin inexacta, incorrecta e incompleta, el esfuerzo del desarrollo se daa, quizs lejos de reparar. La produccin de la documentacin requiere el compromiso de tiempo, de esfuerzo y de dinero. Es responsabilidad de la administracin asegurar la distribucin efectiva de estos recursos, reconociendo la importancia de la documentacin para la calidad y el xito del producto de software. La produccin de la documentacin de los proyectos de software es un problema para la administracin de las organizaciones que producen software. La necesidad de la documentacin es universalmente aceptada, pero el trabajo de documentar es universalmente menospreciado. El dilema para las administraciones es reconciliar estas diferencias aparentemente irreconciliables. El primer paso bien puede ser hacer una determinacin verdaderamente administrativa de los procesos de documentacin. En las discusiones en cuanto a la documentacin del software, es importante especificar cul es el significado de la documentacin. Y, en la planificacin de la documentacin, es importante mirar todas las partes del proceso de desarrollo del software y garantizar que cada parte est documentada. La base de una buena documentacin descansa en dos elementos: mejores tcnicas de documentacin y esfuerzos administrativos. Una vez que los administradores entienden claramente qu es la documentacin del software pueden planificar, apoyar y controlar mejor el proceso de desarrollo de la documentacin del software. Esto es aplicable a todos los tipos de software, desde el programa ms simple hasta la serie de software ms compleja o software de sistema. Estn cubiertos todos los tipos de documentacin del software referentes a todas las etapas del ciclo de vida del software. Los principios de la administracin de la documentacin del software son los mismos, cualquiera sea el tamao del proyecto. Para los proyectos pequeos, gran parte del detalle dado en este

documento puede no aplicarse, pero los principios siguen siendo los mismos. Los administradores pueden ajustar las recomendaciones a sus necesidades especficas. Proporciona una gua desde el punto de vista de la administracin de la documentacin del software, por lo cual no se brindan, por ejemplo, consejos detallados sobre la estructura y el contenido de los documentos. 1. Papel de los administradores Tanto la direccin tcnica como administrativa pueden proporcionar soluciones a los problemas de la documentacin del software, pero debido a su importancia fundamental, este documento enfatiza la direccin administrativa de la documentacin del software. Los administradores deben comprometer su organizacin al esfuerzo de desarrollo y mantenimiento de la documentacin y apoyar ese esfuerzo para integrarlo en el proceso de desarrollo del software, garantizando un clima de organizacin orientado al trabajo de la documentacin mediante el establecimiento de las polticas, de las normas, de los procedimientos, de las asignaciones de los recursos necesarios y de los planes de documentacin del software. La efectividad del papel administrativo descansa sobre tres elementos: a) El compromiso de la administracin para el desarrollo y el mantenimiento de la documentacin del software. Este compromiso requiere el reconocimiento de que la documentacin del software es importante y que tiene que ser planificada, escrita, revisada, aprobada, producida, distribuida y mantenida. b) El apoyo de la administracin al personal comprometido con la documentacin. Este apoyo consiste en ofrecer la gua administrativa y los incentivos necesarios para que el personal pueda producir la documentacin con la calidad requerida y la provisin de los recursos necesarios para facilitar el trabajo de desarrollo y mantenimiento de la documentacin del software. c) La evidencia del compromiso y el apoyo administrativo. Esta evidencia consiste en: el establecimiento de la poltica de documentacin mediante directivas publicadas; el establecimiento de las normas de documentacin identificadas para todos los aspectos de la documentacin del software; el establecimiento de los procedimientos de documentacin mediante directivas publicadas; el establecimiento de los procedimientos para asegurar y auditar la calidad de la documentacin del software y ofrecer los medios necesarios para ello; el aseguramiento de la asignacin de los recursos adecuados para la documentacin; el establecimiento de la planificacin de la documentacin emprendida como una parte integral del proceso de desarrollo del software;

 el establecimiento de un proceso de revisin continua emprendido para garantizar el cumplimiento de la poltica, de las normas, de los procedimientos y de los planes de documentacin del software. 2. Funciones de la documentacin del software Para administrar de forma efectiva el proceso de desarrollo y mantenimiento de la documentacin del software es importante darse cuenta de las diferentes funciones ejecutadas por la documentacin del software. La documentacin del software puede ser considerada que tiene seis funciones principales: a) Comunicacin para la administracin b) Comunicacin tarea - tarea c) Aseguramiento de la calidad d) Instruccin y referencia e) Soporte del software f) Referencia histrica 2.1 Comunicacin para la administracin. Durante el desarrollo del software, la administracin necesita ser informada del progreso, de los problemas y d las expectativas. Los informes peridicos que rastrean el progreso contra los cronogramas y planes del proyecto para el prximo perodo proporcionan mecanismos de control y visibilidad para el proyecto. 2.2. Comunicacin tarea -tarea. La mayora de los proyectos de desarrollo de software se dividen en tareas, llevadas a cabo con frecuencia por diferentes grupos. Generalmente: los especialistas de la actividad objeto de estudio inician el proyecto formulando las necesidades del cliente; los analistas analizan y determinan los requerimientos del software; los diseadores disean el software; los programadores codifican el software; los especialistas en publicaciones producen la documentacin del usuario de acuerdo con la poltica y las normas de documentacin del software; los especialistas de aseguramiento de la calidad del software y los auditores informticos evalan la integridad y la ejecucin total del software y de su documentacin; los programadores de mantenimiento mantienen actualizado el software, corrigiendo los errores detectados, perfeccionndolo o adaptndolo a los cambios en los requerimientos del nuevo ambiente de operacin (de hardware, de software y organizativo funcional).

Estas personas necesitan un medio de comunicacin con otras personas, las cuales proporcionan la informacin que puede ser reproducida, distribuida y referida segn se necesite. La mayora de las metodologas de desarrollo de software establecen documentos formales para la comunicacin tarea - tarea. Por ejemplo, los analistas presentan las especificaciones formales del anlisis de los requerimientos a los diseadores y stos les dan a los programadores las especificaciones formales del diseo. 2.3 Aseguramiento de la calidad. Aquellos que tienen la responsabilidad del aseguramiento de la calidad del software, para llevar a cabo sus tareas requieren de la documentacin del desarrollo y de la documentacin del producto. 2.4 Instruccin y referencia. La documentacin es necesaria para posibilitar a los operadores, a los usuarios, a los administradores y a otras personas interesadas, entender y utilizar el producto de software. 2. 5 Soporte de/ software. Los programadores de mantenimiento requieren de las descripciones detalladas del software de modo que puedan localizar y corregir los errores, as como mejorar o adaptar el software segn los cambios en los requerimientos del nuevo ambiente de operacin (de hardware, de software y organizativo funcional). 2.6 Referencia histrica. La documentacin se necesita como una referencia histrica para la planificacin y desarrollo de futuros proyectos de software, ya que como la tecnologa cambia tan rpidamente, los productores de software pueden revisar los proyectos previos para averiguar qu se ha intentado, qu ha trabajado bien y qu se ha rechazado como inservible por alguna razn. Tambin puede impedir un comienzo en falso de un proyecto futuro, ya que refleja las soluciones efectivas y no efectivas para el software y los problemas de la actividad objeto de estudio. Esta documentacin puede tambin ayudar en la transferencia y conversin del software a nuevos ambientes. Esta funcin con frecuencia es pasada por alto. 3. Establecimiento de la poltica de documentacin del software La poltica de documentacin que es preparada y sustentada por la administracin principal, proporciona una gua para la toma de decisiones en todos los niveles ms bajos de la organizacin. La poltica proporciona amplia direccin, pero no prescripciones detalladas sobre qu hacer o cmo hacerlo. Debido a que la documentacin juega un papel vital en todas las etapas del ciclo de vida del software, debe ser preparada una declaracin formal de la poltica. Cada afectado por la poltica deber ser informado de ello y deber comprenderla. La poltica formalizada, bien escrita y publicada establece la disciplina requerida para la administracin efectiva de la documentacin del software. La poltica deber apoyar los siguientes elementos bsicos para que la documentacin sea efectiva: a) Los requerimientos de documentacin deben cubrir todo el ciclo de vida del software. La documentacin es requerida desde las primeras etapas de un proyecto y tiene que estar

disponible y ser mantenida a travs del proceso de desarrollo del software. Despus que el desarrollo termina, la documentacin se necesita para el uso y el mantenimiento del software. b) La documentacin debe ser administrada. La direccin y el control se requieren para obtener y mantener la documentacin. Los administradores y los especialistas en publicaciones deben preparar planes detallados de documentacin del software que contemplen: los documentos a producir en cada proceso del desarrollo del proyecto; los cronogramas del proceso de desarrollo de la documentacin del software; las responsabilidades de todos y cada una de las personas que intervienen en el proceso de desarrollo y mantenimiento de la documentacin del software; los recursos necesarios para el desarrollo y el mantenimiento de la documentacin del software; los procedimientos de revisin de la documentacin del software; los procedimientos de aseguramiento de la calidad de la documentacin del software. c) La documentacin debe ser apropiada a sus lectores. Los lectores pueden ser administradores, analistas, profesionales sin experiencia en informtica, programadores de mantenimiento, personal eclesistico, etc. En dependencia de las tareas ejecutadas, requieren diversos grados de detalle y diferentes presentaciones del material. Por ello, es conveniente disponer de un especialista en publicaciones, el cual debe estar encargado de disear adecuadamente los diferentes tipos de documentacin destinados a los diferentes lectores. d) El proceso de desarrollo y mantenimiento de la documentacin debe estar integrado en todo el proceso de desarrollo del software debe ser definido a lo largo de los diferentes procesos del desarrollo del software. e) Las normas de documentacin del software deben estar identificadas y deben ser utilizadas. Dondequiera que sea posible, deben ser adoptadas las normas internacionales o nacionales existentes. En otro caso, la organizacin deber desarrollar sus propias normas. f) Las herramientas de apoyo deben estar especificadas. Dondequiera que sea econmicamente factible deben ser utilizadas las herramientas que ayudan al desarrollo y al mantenimiento del software, incluyendo la documentacin. Aunque no es esencial, seria preferible utilizar para la preparacin y mantenimiento de la documentacin, la misma herramienta de software de ayuda utilizada para desarrollar y mantener actualizado el software, a fin de poder desarrollar juntos el software y su documentacin. Esto tiene muchas ventajas, tales como que se puede crear un formato automatizado para los documentos, obtener la numeracin automtica de los epgrafes, crear automticamente las tablas de contenidos y otros ndices, etc. En la figura 3 se proporciona un cuestionario que contiene una lista de comprobacin de la poltica de documentacin del software, la cual sirve de ayuda para desarrollar una poltica o para evaluar la utilidad y la integridad de una poltica existente. 4. Establecimiento de las normas de documentacin del software Dentro de una organizacin deben ser establecidas normas de documentacin del software para:

a) El modelo de ciclo de vida del software. b) Los tipos de documentos e interrelaciones. c) La identificacin de los documentos. d) La estructura y el contenido de los documentos. e) Los formatos de los documentos. f) La calidad de los documentos. Estas normas determinan cmo deben ser llevadas a cabo las tareas de documentacin y proporcionan el criterio para juzgar la completitud, la utilidad y la aptitud de la documentacin del software producida dentro de la organizacin. Tanto las normas de documentacin que hayan sido desarrolladas especficamente para los requerimientos propios de una organizacin como las adoptadas de una fuente existente proporcionan lineamientos de carcter general que son aplicables a muchas situaciones diferentes. Para adaptar los lineamientos generales a proyectos especficos es necesario el criterio administrativo. La aplicacin de las normas de documentacin en proyectos especficos de una organizacin posibilitar a los administradores de proyecto determinar lo siguiente: a) los tipos de documentos que deben ser producidos. b) La cantidad de documentacin que va a ser proporcionada. c) El contenido de los documentos. d) Los formatos que deben tomar los documentos. e) El nivel de calidad que debe ser alcanzado. f) En el momento en que los documentos deben ser producidos. 9) El momento en que los documentos deben estar terminados h) Las personas que deben producir los documentos. i) El momento en que los documentos deben estar terminados. j) Las personas que deben producir los documentos. k) Las personas que deben mantener actualizados los documentos. l) La forma en que la documentacin debe ser almacenada, mantenida y comunicada. m) La horma en que deben de ser distribuidos los documentos originales y las versiones actualizadas.

De esta manera, los lineamientos generales que proporcionan las normas de documentacin del software sirven e gua y no de especificaciones rgidas. En las organizaciones donde el desarrollo del software est regido mediante la firma de contratos, en los mismos, adems de especificarse las normas de documentacin a las cuales se deben de ajustar los documentos para su aceptacin, se debe especificar: a) Los tipos de documentos a ser suministrados. b) El nivel de calidad requerido para cada tipo de documento. d) Los procedimientos para la revisin y la aprobacin de los documentos. CUESTIONARIO PARA LA ADMINISTRACIN DE LA DOCUMENTACIN DEL SOFTWARE 4.1 Seleccin de un modelo de ciclo de vida de/ software. Existe un nmero de modelos del ciclo de vida del software, con diferente terminologa para las diversas etapas. Las etapas definidas en los diferentes modelos del ciclo de vida del software varan de una metodologa de desarrollo de software a otra y an de un tipo de proyecto de software a otro, pero de forma general, todos los modelos del ciclo de vida contemplan los procesos siguientes: a) Inicio. Se parte de una solicitud formal del desarrollo de un proyecto de software para satisfacer las necesidades de un cliente y resolver uno o ms problemas en la actividad objeto de estudio bajo ciertas restricciones tcnicas, financieras y de tiempo. b) Anlisis (Estudia o Investigacin) preliminar. Evaluacin de la actividad objeto de estudio, anlisis preliminar de los requerimientos del software, determinacin de la factibilidad del proyecto, evaluacin de diferentes alternativas de solucin o estrategias de desarrollo del proyecto, propuesta de la mejor solucin y administracin (organizacin, planificacin y control) del proyecto de software propuesto. c) Anlisis detallado (Requerimientos del software). Especificacin de las caractersticas o propiedades que el software debe poseer. d) Diseo preliminar (general). Transformacin de los requerimientos del software, definiendo la estructura arquitectnica del software, as como la planificacin de la implantacin y de las pruebas de aceptacin del software. e) Diseo detallado. Transformacin de la estructura arquitectnica del software, definiendo en forma detallada las caractersticas del diseo de los elementos componentes de ms bajo nivel del software, la estructura de los datos y los procedimientos automatizados y manuales. f) Programacin. Traduccin de cada descripcin detallada del diseo a cdigo a travs de la escritura de los programas, la depuracin, las pruebas (de unidad y de integracin de los elementos componentes del software: mdulos, subsistemas, programas, etc.) y el desarrollo de la documentacin del producto de software. g) Pruebas de aceptacin (de] productor y del cliente). Comprobacin de que el software satisface las necesidades del cliente y de los usuarios finales cumpliendo con todos los requerimientos de calidad establecidos tanto explcitamente por el cliente como implcitamente por el productor.

h) Implantacin y entrega del software. Introduccin del software terminado que ha sido liberado para su uso en su ambiente de operacin. i) Operacin. Utilizacin continuada del software por los usuarios finales. j) Mantenimiento. Revisiones peridicas posteriores a la implantacin del software mientras ste se encuentra en uso y modificacin del software para dar solucin a los problemas no detectados durante el proceso de desarrollo, tales como la eliminacin de los fallos mediante la correccin de los errores no detectados hasta el momento, el perfeccionamiento, la ampliacin o el mejoramiento de las posibilidades del software y la adaptacin del software a las nuevas condiciones o cambios en los requerimientos del ambiente de operacin (de hardware, de software u organizativo funcional). k) Retirada. Desactivacin definitiva del software, retirndolo de su utilizacin (final de su vida til). Los administradores deben seleccionar un modelo de ciclo de vida del software apropiado y garantizar que sea aplicado en su organizacin. Desde el punto de vista de la documentacin del software, no importa qu modelo se adopte para cualquier proyecto de software en particular, lo importante es que las etapas sean claramente definidas, planificadas y programadas, as como que la documentacin asociada est definida, sea planificada y sea producida y actualizada en cada etapa. Los administradores encontrarn que, estando bien definidas las etapas y las tareas asociadas, le ayudarn a monitorear el progreso de cualquier proyecto de software. La produccin de la documentacin asociada con una etapa especfica puede, por ejemplo, ser utilizada como un punto de comprobacin para la revisin, aprobacin y terminacin de la etapa antes del comienzo de la prxima. Las buenas intenciones iniciales tienen que estar seguidas por acciones, insistiendo que la documentacin resultante de cada etapa est regida por una norma y sea terminada antes de que se comience la prxima etapa. 4.2 Definicin de los tipos de documentos. La definicin que se brinda no es exhaustiva ni definitiva, pero servir como una lista de comprobacin de los principales tipos de documentos del software que los administradores debern estipular al definir su norma de tipos de documentos. La documentacin del software comprende tres categoras: a) La documentacin del desarrollo b) La documentacin del producto c) La documentacin de administracin del proyecto 4.2.1 Documentacin del desarrollo. Documentos que describen el proceso de desarrollo del software, los cuales especifican los requerimientos que el software tiene que cumplir, el diseo del software, cmo deber ser probado y cmo va a ser asegurada su calidad. La documentacin del desarrollo tambin incluye las descripciones tcnicas detalladas del software (lgica del programa,

interrelaciones entre programas, formatos y almacenamiento de los datos, etc.). El compromiso para la documentacin del desarrollo es frecuentemente hecho como parte de una metodologa de desarrollo de software. Los documentos del desarrollo sirven para cinco propsitos: a) Servir de vehculo de comunicacin entre todas las actividades involucradas en el proceso de desarrollo. Registran detalles de las decisiones hechas acerca de los requerimientos, del diseo, de la codificacin y de la prueba del software. b) Delimitar las responsabilidades del equipo de desarrollo. Definen quin hace qu y cundo lo hace, mediante la especificacin del papel del personal de software, del personal de la actividad objeto de estudio, del personal de documentacin, del personal de aseguramiento de la calidad y de cualquier otro personal involucrado en el proceso de desarrollo. c) Actuar como puntos de comprobacin que le permiten a los administradores evaluar el progreso del desarrollo. Si los documentos del desarrollo faltan, estn incompletos o no actualizados, los administradores pierden una herramienta importante para rastrear y controlar el progreso del proyecto de software con el objetivo de dirigir los esfuerzos administrativos hacia donde sea necesario mantener el proyecto de acuerdo con el cronograma de desarrollo y al mismo tiempo asegurar que la documentacin del desarrollo sea terminada en el tiempo previsto. d) Formar la base de documentacin de soporte del software requerida por los programadores de mantenimiento como parte de la documentacin del producto. e) Registrar la historia del desarrollo del software, de modo que sirva de referencia disponible para su uso posterior. Los documentos tpicos del desarrollo son: a) Los estudios de factibilidad y las solicitudes de inicio. b) Las especificaciones de los requerimientos. c) Las especificaciones del diseo, incluyendo las especificaciones de los programas y datos en el enfoque estructurado y la especificacin de las clases y subsistemas en el enfoque orientado a objetos. d) los planes de desarrollo. e) Los planes de prueba e implantacin. f) Los planes, las normas y los cronogramas del aseguramiento de la calidad. g) La informacin de control y seguridad. 4.2.2 Documentacin del producto. Documentos que describen el resultado del proceso de desarrollo del software. La documentacin del producto proporciona la informacin necesaria para el uso y el mantenimiento del producto de software.

Un producto de software es un conjunto de programas de computacin bien probados y mantenidos por una organizacin responsable y puede o no ser producido por una fuente comercial, pero por estar dirigido para un amplio uso y aplicacin debe estar completamente documentado. Para un programa experimental o temporal orientado para el uso privado o personal, que tenga una corta vida o que su uso est limitado a los elaboradores la documentacin puede ser mnima. Si un programa va a ser utilizado por otros que no son los elaboradores, tiene que estar documentado como un producto. La documentacin del producto sirve para tres propsitos a) Proporcionar informacin de entrenamiento y referencia para cualquiera que vaya a utilizar o a operar el producto de software. b) Permitir el mantenimiento del software por aquellos programadores que no lo han desarrollado. c) Promover la comercializacin o la aceptacin del producto de software. La documentacin del producto incluye los documentos para los tipos de lectores siguientes: a) los usuarios finales, quienes con el software captan los datos, recuperan la informacin y resuelven los problemas. b) Los operadores, quienes explotan el software en un sistema de computadora. c) los programadores de mantenimiento, quienes mantienen actualizado el software, corrigindolo, perfeccionndolo o adaptndolo a los nuevos requerimientos del ambiente de operacin (de hardware, de software y organizativo funcional). La documentacin del producto puede incluir los siguientes documentos: a) Las guas y los materiales para los administradores, quienes supervisan el uso del software. b) Los materiales de promocin, que anuncian la disponibilidad del producto de software y detallan sus funciones y los requerimientos del ambiente operacional (de hardware, de software y organizativo funcional), etc. c) La informacin general, que describe el software para cualquier interesado en l. Los documentos tpicos del producto son: a) Los manuales de entrenamiento. b) Las guas del usuario y los manuales de referencia. c) Los manuales de soporte del software orientados al mantenimiento. d) Los folletos y los plegables de informacin del producto.

Otros documentos que conforman la documentacin del producto son los materiales especficos de informacin/promocin (resmenes para la administracin, descripciones del producto, anuncios internos y externos del producto, etc.) los cuales dependen del software que est siendo desarrollado. Estos documentos, sin embargo, debern ser planificados y producidos como parte del proceso de desarrollo del software. 4.2.3 Documentacin de la administracin del proyecto. Documentos que describen la administracin del proceso de desarrollo del software; creados sobre la base de la informacin de administracin del proyecto tales como: a) Los cronogramas para cada etapa del proceso de desarrollo y los registros de los cambios del cronograma. b) Los registros de los cambios acordados para el software. c) Los registros de las decisiones relacionadas con el desarrollo. d) Las definiciones de las responsabilidades. Los documentos tpicos de la administracin son: a) Manual de cambios. b) Informes de evaluacin. Esta documentacin proporciona la informacin relacionada con la vida de un software desde el punto de vista de la administracin. 4.3 Definicin de la calidad de los documentos. Los administradores debern establecer las normas para el nivel de calidad apropiado a diferentes tipos de documentos y diferentes tipos de proyectos, y debern determinar cmo esa calidad va a ser lograda y mantenida. Las consideraciones de calidad se aplican al contenido, a la estructura y a la presentacin de la documentacin: a) la calidad del contenido puede ser medida en funcin de la correccin, la completitud y la claridad. b) La calidad de la estructura puede ser medida por la facilidad con la cual el lector es capaz de localizar la informacin. c) La calidad de la presentacin deber ser apropiada al tipo de proyecto. Por ejemplo, una gua del usuario pudiera tomar la forma de un conjunto de pginas mecanografiadas y presilladas juntas, o podra ser un componente de un libro con extensas ilustraciones diseadas por un experto en grficos. La calidad de cada documento tiene que ser una decisin consciente durante su planificacin. Las decisiones acerca de la calidad de la documentacin dependen en gran medida de los recursos que se dispongan para asegurarla. 4.4 Definicin de los formatos de los documentos.

Los formatos estandarizados de los documentos son importantes para el control de la calidad, para la legibilidad y para la facilidad de mantenimiento de los documentos. la informacin puede ser presentada en una variedad de formatos. Las especificaciones del diseo, por ejemplo, pueden estar escritas sobre formas predefinidas. El entrenamiento al usuario puede ser llevado a cabo por medio de programas de entrenamiento en lnea, en las aulas o a travs de los manuales del usuario y de entrenamiento. Las formas prediseadas para especificar los requerimientos del software y para detallar las especificaciones de los programas y del almacenamiento pueden proporcionar una comunicacin ms eficiente entre las tareas que los informes escritos. Los formatos de los documentos pueden variar de proyecto a proyecto. Dependern de factores tales como, el tamao del proyecto, el lector al que estn orientados, el nmero de etapas identificadas y el presupuesto de la documentacin. Los formatos de los documentos que conforman la documentacin del producto orientada a los usuarios tiene sus caractersticas muy especficas. En el diseo de los formatos, deber pensarse cules documentos sern traducidos para la distribucin internacional. La economa tambin choca con los formatos de los documentos. El costo de desarrollar los manuales de entrenamiento en lnea puede ser muy grande. Teclear y fotocopiar los manuales es menos caro que su composicin e impresin, especialmente si los documentos son revisados con frecuencia. Dentro de cada organizacin productora de software es til establecer una norma propia de "formato estndar de la casa", la cual debe incluir la descripcin de los formatos para la cubierta frontal para ser adaptados en los diferentes tipos de documentos que conforman la documentacin del software. Las normas de una organizacin para los formatos de los documentos deben ser definidas de modo tal que le permitan flexibilidad a los administradores del proyecto en la seleccin de los formatos apropiados para sus proyectos. 4.5 Definicin de un sistema de identificacin de los documentos. Es esencial para el control efectivo de la documentacin establecer una norma por medio de la cual se identifiquen los documentos. La identificacin de la informacin debe incluir: a) El ttulo del documento. b) El nmero de referencia del documento. c) El nmero de la versin del documento. d) La fecha de emisin y de revisin. e) El (los) autor(es). f) La(s) autoridad(es) de aprobacin. g) La identificacin de la proteccin y del derecho de copia. h) La denominacin de la organizacin del productor.

Donde los documentos vayan a ser emitidos en forma de hojas intercambiables, cada pgina deber estar identificada de forma nica (por ejemplo, con el nmero del tema y el nmero de la pgina). En la figura 3 se muestra un cuestionario que contiene una lista de comprobacin de las normas de documentacin del software. 5 . Establecimiento de los procedimientos de documentacin del software Para instrumentar la poltica de documentacin del software de la organizacin se deben establecer los procedimientos de documentacin del software. Los procedimientos definen las siguientes secuencias lgicas del proceso de documentacin del software: a) La planificacin de la documentacin del software. La administracin deber establecer un procedimiento para la planificacin de los documentos que conforman la documentacin en cada proyecto de software. b) La preparacin de los documentos. La administracin deber establecer un procedimiento para la elaboracin y preparacin de los anteproyectos de los documentos originales que sern sometidos a un proceso de revisin formal. La elaboracin de los documentos deber realizarse de acuerdo a las normas de documentacin del software y de aseguramiento de la calidad de la documentacin del software establecidas. El procedimiento debe contemplar el establecimiento y la utilizacin de las herramientas de software seleccionadas para el desarrollo de la documentacin de forma automatizada. c) El control de la documentacin del software. La administracin deber establecer un procedimiento para controlar la documentacin del software como elemento componente de la configuracin del software, tanto a nivel de proyecto como a nivel de la organizacin productora de software. En cada proyecto de software se debe designar a un bibliotecario del proyecto que tenga la responsabilidad de recopilar la informacin del desarrollo del proyecto, mantener un conjunto de informacin principal y mantener un ndice de la documentacin del proyecto. En dependencia del tamao y la complejidad del proyecto, las tareas de control de la documentacin pueden ser asignadas a algn miembro actual del proyecto para que se dedique a ello a tiempo parcial o requieran de un personal adicional a tiempo completo. Adems para la recopilacin de los documentos y la preparacin de un ndice que permita encontrar los documentos, en la biblioteca del proyecto se debe mantener: Una cronologa breve de los eventos significativos; Los registros de los estimados mensuales del tiempo de mquina; Los registros de los estimados mensuales del tiempo del personal; La lista de los cambios de los estimados;

 Un resumen del comportamiento de los tiempos consumidos. A nivel de organizacin, la administracin deber designar a un bibliotecario que tenga la responsabilidad de: Controlar la documentacin de todos los proyectos de software; Mantener un catlogo de la documentacin del software, como parte del proceso de administracin de la configuracin del software; Controlar las modificaciones y las versiones de los documentos que conforman la documentacin del software; Registrar e informar el estado de la documentacin del software y de las solicitudes de cambio; Verificar la completitud y la correccin de todos los documentos que conforman la documentacin del software; Controlar el almacenamiento, la manipulacin y la entrega de los documentos que conforman la documentacin del software. d) La revisin de los documentos. La administracin deber establecer un procedimiento de revisin formal de todos los tipos de documentos que conforman la documentacin de los proyectos de software (documentacin del desarrollo, del producto y de administracin del proyecto). La revisin de los anteproyectos y versiones finales de los documentos debe hacerse contra las normas de documentacin del software y normas de aseguramiento de la calidad de la documentacin establecidas. e) La aprobacin de los documentos. La administracin deber establecer un procedimiento para la aprobacin de todos y cada uno de los documentos resultantes de cada etapa del proceso de desarrollo del software. Los documentos deben ser aprobados una vez que los revisores estn de acuerdo para formalizar la constancia de la aceptacin. f) La produccin de los documentos. La administracin deber establecer un procedimiento para la reproduccin de los documentos originales y para el empaquetamiento de la documentacin del software. Atendiendo a los diferentes tipos de documentos se utilizar el mtodo ms apropiado (mecanografa y fotocopia; composicin e impresin; etc.) g) El almacenamiento de la documentacin del software. La administracin deber establecer un procedimiento para el almacenamiento de los documentos originales que conforman la documentacin del software, ya que esto constituye un elemento vital para toda la organizacin. La documentacin del software representa una significativa inversin financiera en recursos materiales, personal y tiempo; as como representa todo el esfuerzo desplegado para la obtencin del software. El local para almacenar los documentos originales debe ser un lugar adecuado, protegido y seguro y que rena los requerimientos mnimos necesarios para la custodia y conservacin de la documentacin del software Los soportes (papel y magnticos) que contienen la documentacin del software debern ser mantenidos durante todo el periodo de vida til del software.

h) El respaldo de los documentos. La administracin deber establecer un procedimiento para realizar duplicados o copias de seguridad a la documentacin del software para reponer los documentos originales (en soportes de papel y/o magntico) ante la prdida o el deterioro de los mismos. Las copias de respaldo debern almacenarse en un lugar diferente a donde se mantienen almacenados los documentos originales para que en caso de desastre (naturales o provocados por el hombre) no se ocasione una prdida irreparable. Aquellos documentos desarrollados para consulta en lnea debern ser duplicados en soportes magnticos, de modo tal que puedan ser restablecidos cuando sea necesario. i) La actualizacin y la distribucin de la documentacin. La administracin deber establecer un procedimiento para modificar los documentos originales y conformar la documentacin del software a partir de los cambios que se autoricen realizar para mantenerlos actualizados. Adems deber establecer un procedimiento para la distribucin de los documentos actualizados a todos los usuarios registrados. j) La depuracin de la documentacin. La administracin deber establecer un procedimiento para la depuracin de los documentos que conforman la documentacin del software una vez que ste haya llegado al final de su vida til, teniendo en cuenta el periodo de permanencia establecido para los diferentes tipos de documentos y lo establecido en cuanto a la clasificacin de los mismos. Los procedimientos tambin debern identificar los puntos de comprobacin y los mtodos del aseguramiento de la calidad de la documentacin. En la figura 3 se proporciona un cuestionario que contiene una lista de comprobacin de los procedimientos de documentacin del software. 6. Asignacin de recursos para la documentacin del software. Para lograr un software con calidad es necesario que su correspondiente documentacin tenga calidad y para ello tienen que disponerse los recursos necesarios. Los recursos requeridos para la documentacin del software son principalmente: a) El personal; b) Las facilidades; c) El financiamiento. 6.1 Personal. Tanto el trabajo tcnico como el administrativo depende de las personas. Las normas ni las metodologas pueden sustituir el empleo de un personal que rena las caractersticas apropiadas. Algunos entrenamientos en tcnicas de documentacin y de escritura tcnica son tiles, pero sin embargo el requerimiento principal es lograr disponer de un buen personal tanto para el desarrollo del software como de su documentacin. El proceso de desarrollo de la documentacin del software tiene asignado responsabilidades especficas para el personal con conocimiento de: a) Ingeniera del software, para la documentacin del desarrollo;

b) Actividad objeto de estudio, para proporcionar informacin acerca de la aplicacin a la cual el software est orientado; c) Documentacin, para desarrollar la documentacin del producto. Es importante que el personal est entrenado completamente en las tcnicas de documentacin y que cada grupo entienda y cumpla completamente su responsabilidad en el desarrollo y en el mantenimiento de la documentacin: a) Los diseadores y programadores de software son responsables de preparar la documentacin del desarrollo que describe los productos o sus tareas y de proporcionar la documentacin de soporte del software. b) Los especialistas en la actividad objeto de estudio tienen la responsabilidad de proporcionar informacin para los estudios de factibilidad, las especificaciones de los requerimientos, los planes de prueba, los planes de aseguramiento de la calidad, los planes para la introduccin del software en su ambiente operacional y otros tipos de cronogramas, o pueden producir partes de los mismos. c) Los especialistas en publicaciones son responsables de conformar generalmente la documentacin de entrenamiento del usuario, de referencia y de informacin y promocin del software. 6.2 Facilidades Es importante considerar la provisin de las facilidades de software y de hardware adecuadas y apropiadas para las tareas de desarrollo y mantenimiento de la documentacin. Las herramientas de software deben estar disponibles para el desarrollo y el mantenimiento de la documentacin. Estas pueden ser utilizadas para mejorar la eficiencia de muchos de los procesos de documentacin y del uso de las normas de documentacin de una organizacin. Las herramientas automatizadas de ayuda a la documentacin utilizadas exitosamente en el desarrollo y en el mantenimiento de la documentacin pueden proporcionar diagramas, ndices, listados de los elementos de datos y referencias cruzadas entre las subrutinas y otros componentes del programa. Tales facilidades evitan la tediosa reescritura del anteproyecto de los documentos y permiten la reimpresin automtica de los documentos actualizados. La administracin, atendiendo a las diferentes lneas de desarrollo de software, debe establecer y facilitar el uso de herramientas de software estndar de ayuda al desarrollo y mantenimiento de la documentacin, tales como: a) Herramientas CASE; b) Generadores de programas; c) Documentadores de programas; d) Herramientas de ayuda a la administracin de proyectos; e) Procesadores de texto con posibilidades grficas y correccin ortogrfica;

f) Publicadores; g) Traductores automticos para diferentes idiomas. Adems, la administracin debe garantizar la provisin de los equipos perifricos necesarios para la impresin y reproduccin de la documentacin, tales como: a) Fotocompositoras; b) Impresoras de alta calidad. 6.3 Financiamiento. Es importante que los costos de la documentacin se identifiquen como elementos dentro del presupuesto del proyecto, ya que ellos constituyen una parte muy significativa del costo del desarrollo del software. El costo del proceso de documentacin tiene que reflejarse en el presupuesto y en los planes del proyecto. El financiamiento es necesario para apoyar a los escritores y a las facilidades que utilizan, as como el almacenamiento, a la reproduccin, a la distribucin y al mantenimiento de los documentos. Los servicios de los especialistas de documentacin u otras personas familiarizadas con este tipo de actividad debern ser solicitados durante la planificacin para ayudar a establecer un presupuesto razonable. 7. Planificacin de la documentacin del software. Un plan de documentacin del software establece: a) Qu se va a hacer? (los documentos que se van a producir). b) Cmo se va a hacer? (la forma en que los documentos sern desarrollados). c) Cundo se va a hacer? (el momento en que los documentos se deben desarrollar). d) Quin lo va a hacer? (los responsables de desarrollar los documentos). El plan de documentacin del software puede formar parte del plan global del proyecto o puede ser un documento independiente. Par los proyectos pequeos, informales el plan puede ser solamente una pgina. Para proyectos mayores, puede ser un documento amplio que cumpla con las normas establecidas y est sujeto a un procedimiento formal de revisin y aprobacin. El plan de documentacin del software deber ser distribuido a todos los miembros del equipo de desarrollo y a cualquier otro afectado por l. Deber delimitar claramente las responsabilidades de todas aquellas personas involucradas en el desarrollo y mantenimiento de la documentacin. El plan de documentacin del software debe incluir aspectos tales como: a) La estructura general de la documentacin; b) Los tipos de documentos y su contenido; c) Los formatos y la calidad de los documentos; d) La forma de identificacin de los documentos;

e) La compilacin y el almacenamiento de los documentos; f) La distribucin de los documentos; g) El cronograma de la documentacin. Programacin detallada de los procesos de documentacin, de los documentos resultantes de cada proceso del desarrollo del software, de los puntos de revisin y del personal responsable de la planificacin, escritura, revisin y distribucin de la documentacin. El cronograma de la documentacin debe asignar tiempo para: La planificacin de los documentos; La revisin del cumplimiento del plan de documentacin y del contenido de la documentacin; La preparacin de los anteproyectos de los documentos originales y su revisin para la precisin tcnica, la completitud y la aptitud; La edicin para incorporar los comentarios que puedan surgir de las revisiones; La obtencin de las aprobaciones; La traduccin hacia otros idiomas (del Espaol al Ingls); La produccin; La distribucin. La planificacin del proyecto comienza desde su inicio y el plan del proyecto debe ser revisado a lo largo de su desarrollo. El plan de documentacin, el cual forma parte del plan del proyecto, como cualquier plan indica actividades futuras y est sujeto a cambios segn cambian las necesidades. En base al resultado de las revisiones regulares que se efectan durante el desarrollo del proyecto, el plan de documentacin del software deber ser actualizado y los cambios propuestos deben ser incorporados al plan de desarrollo del proyecto. Los administradores debern establecer las prioridades para la preparacin de la documentacin del software y balancear la necesidad de la documentacin contra las necesidades del proyecto en general.

CAPITULO 3 Tipos de Documentos Establece los tipos de documentos que se producen durante los diferentes procesos del desarrollo del software, as como sus interrelaciones.

A pesar de la diversidad de software, existen similitudes fundamentales. Siempre existe la necesidad de establecer y justificar los recursos, tales como el personal, los materiales y el financiamiento necesarios para el desarrollo e implantacin de un proyecto de software, ya sea grande o pequeo y la necesidad de documentar adecuadamente todos sus aspectos. La profundidad con que se desarrollen los diferentes aspectos en la documentacin, depender del tipo de software que se elabore, ya que por ejemplo, los mtodos de operacin deben de ser descritos con ms detalles en un software con ambiente de control de procesos, que en un software con procesamiento en lotes. 1. Tipos de documentos La documentacin del software se puede considerar que comprende tres categoras: a) La documentacin del desarrollo. b) La documentacin del producto. c) La documentacin de la administracin del proyecto. 1. Documentacin del desarrollo. Los documentos que describen el proceso de desarrollo del software especifican los requerimientos que el software tiene que cumplir, el diseo del software, cmo deber ser probado y cmo va a ser asegurada su calidad. La documentacin del desarrollo tambin incluye descripciones tcnicas detalladas del software (sus partes componentes, sus interrelaciones, as como la descripcin detallada de estas partes). Los documentos del desarrollo son: a) Solicitud de inicio del proyecto. b) Informe del estudio de factibilidad. c) Plan del proyecto (de software). d) Solicitud de anlisis. e) Especificacin del anlisis (o de los requerimientos del software). f) Descripcin detallada del diseo. g) Descripcin preliminar del diseo. h) Manual de las pruebas de aceptacin. i) Plan de la implantacin. 2. Documentacin del producto. La documentacin del producto proporciona la informacin necesaria para el uso, mantenimiento, perfeccionamiento, conversin y transferencia de un producto de software. Los documentos del producto son: a) Manual (o Gua) del usuario.

b) Manual [[[(o Gua) de instalacin. c) Manual introductorio. d) Manual (o Gua) de operacin. e) Manual (o Gua) de entrenamiento (Tutor o Clases prcticas). f) Manual (o Gua) de referencia. g) Manual (Gua o tarjeta de referencia rpida. h) Para el enfoque estructurado: Manual de programa; Manual e datos. i) Para el enfoque orientado a objetos: Manual de clases; Manual de subsistemas. j) Descripcin del producto (software). 3. Documentacin de la administran del proyecto. Esta documentacin proporciona la informacin relacionada con la vida de un producto desde el punto de vista de la administracin. Los documentos creados sobre la base de la informacin de administracin del proyecto son: a) Manual de modificaciones. b) Solicitud de cambio. 2. Tipos de Informacin Se establecen dos tipos bsicos de informacin, la administrativa y la tcnica. Estos dos tipos de informacin, deben mantenerse separadas, de forma tal que la informacin tcnica pueda ser ms fcilmente actualizada. 1. Informacin administrativa. Es la informacin de administracin y control del proyecto la cual registra lo que ha sido autorizado y lo que se ha hecho, es una herramienta esencial para monitorear el progreso del proyecto. Esta informacin debe conservarse pero no necesariamente tiene que ser actualizada despus de concluida la implantacin. 2. Informacin tcnica. Es imprescindible para la implantacin, el uso efectivo, el mantenimiento y para la transferencia del software a otro ambiente de software, de hardware u organizativo. Incluye la

descripcin detallada de todos los aspectos del sistema, incluyendo el hardware, el software y los datos. Es esencial que esta informacin sea constantemente actualizada durante todo el ciclo de vida del software. Tambin incluye la de propaganda para la promocin del software, la cual ser necesario elaborar para aquellos productos de software comercial de uso general o aquellos que revistiendo caractersticas particulares, puedan ser utilizados por dos o ms usuarios. 3. Relacin entre los procesos del desarrollo del proyecto y la documentacin Este sistema de documentacin del software relaciona los procesos del desarrollo del proyecto con los documentos que en ellos se generan. Aunque los procesos principales tienen lugar en secuencia, algunos procesos y la preparacin de los documentos se solapan, por ejemplo la preparacin de los manuales de soporte del software debe ser comenzada durante el proceso de diseo. Generalmente, cada proceso del desarrollo del proyecto es iniciado con un documento y concluido con uno o ms documentos. El nmero de etapas y la cantidad de documentos pueden variar para diferentes proyectos en base al modelo de referencia del ciclo de vida seleccionado y a la metodologa de desarrollo que se aplique. Este sistema relaciona los elementos de la documentacin, que normalmente deben aparecer en los documentos generados por cada proceso del desarrollo del proyecto. En la figura 4 se muestra el resumen de las interrelaciones entre los documentos y los procesos que los generan dentro del desarrollo del proyecto. 4. Juegos de documentos Los documentos en los proyectos conforman juegos para los sistemas y sus elementos componentes. En dependencia del tamao del software los manuales pueden separarse o agruparse en uno o ms volmenes. Es permisible la separacin de los documentos en partes o volmenes de un tipo de documento como por ejemplo: el Manual del usuario y el Manual del administrador de la base de datos. Tambin es permisible la unin de algunos documentos aislados en un solo volumen, como por ejemplo el Manual del usuario y el Manual de referencia; el Informe del estudio de factibilidad y el Plan del proyecto de software. El juego de documentos (documentacin) concreto se acuerda con el cliente en el contrato, donde se reflejan los requerimientos no slo del proyecto sino de su documentacin, especificndose las normas de documentacin a las cuales se debe ajustar.