Documentación de Software

Todos los grandes proyectos de desarrollo de software, con independencia de la aplicación, generan una gran cantidad de documentación asociada. Para los sistemas de tamaño moderado, la documentación probablemente llenará varios archivadores; para sistemas grandes, se puede llenar varias habitaciones. Una alta proporción de los costos del proceso de software se incurre en la producción de esta documentación. Por otra parte, los errores de documentación y omisiones pueden dar lugar a errores de los usuarios finales y los fallos del sistema con los consiguientes sus costos y las interrupciones asociadas. Por lo tanto, los gerentes y el software.  

Los ingenieros deben prestar tanta atención a la documentación y sus costos asociados como al desarrollo del software en sí.

Los documentos asociados con un proyecto de software y el sistema están desarrollados para cumplir una serie de requisitos asociados:

1. Deben actuar como medio de comunicación entre los miembros de la Equipo de desarrollo.

2. Deben ser un repositorio de información del sistema para ser utilizado por los ingenieros de mantenimiento.

3. Deben proporcionar información para la gestión de cómo facilitar la planificación, presupuesto y el calendario del proceso de desarrollo de software.

4. Algunos de los documentos debe indicar a los usuarios cómo utilizar y administrar el sistema.

La satisfacción de estas necesidades requiere de diferentes tipos de documentos,  desde los documentos de trabajo informales producidos profesionalmente a través de manuales de usuario.

Los ingenieros de software son generalmente responsables de la producción de la mayor parte de esta documentación, aunque los escritores técnicos profesionales puede ayudar con pulido final de información dada a conocer.

 (Ian Sommerville -Software documentation, Page 2- Lancaster University, UK)

El documento de desarrollo de software contiene todos los preparativos relacionados con el desarrollo de cada unidad o módulo, incluyendo el software, los casos de prueba, resultados de pruebas, homologaciones, y cualquier otro artículo que ayudarán a explicar la funcionalidad del software. El documento es dinámico y es mantenido por el equipo de desarrollo del sistema y en se actualiza constantemente a medida que avanza el desarrollo del sistema.

El modelo tradicional de Proyectos de Software

El modelo de desarrollo tradicional de los proyectos suele ser el modelo de cascada clásico de la ingeniería de software. El proyecto está concebido, financiado y atendido. En ese momento la fase de concepción se mueve en el análisis de requisitos, se desarrollan especificaciones funcionales, y se determina la arquitectura. A continuación, se especifica el diseño, una implementación creada, y la puesta en práctica se comprueba con las especificaciones de la arquitectura. Si todo va bien, el proyecto es aceptado.

En cada etapa del proyecto de software tradicional, se introducen nuevas partes interesadas y los interesados ​​tienen cada vez más bajos estos niveles de enfoque. Si la comunicación del concepto no está clara, los arquitectos pueden llegar a una propuesta que no coincide con el concepto original. Si la arquitectura es más o de menos restringida, la aplicación puede ser insostenible o incompleta. Si la especificación de la validación no coincide con la arquitectura de la aceptación puede no coincidir con el producto aplicado. Por último, si la documentación de usuario final no coincide con la arquitectura y la aplicación, el usuario final va a encontrar que el producto va a llevar mucho tiempo, y será frustrante y costoso. Cualquiera que haya jugado el juego de teléfono y observado cómo ilegible incluso un simple mensaje puede llegar a apreciar cómo un pequeño defecto en la cadena de comunicación de un proyecto complejo puede conducir a la catástrofe en el producto final.

El modelo de proyecto de desarrollo de software abierto

El modelo de desarrollo de software abierto difiere del modelo tradicional en varios aspectos importantes.

En primer lugar, el concepto y los requisitos normalmente vienen directamente desde el usuario final, y por lo general se acompañan de una implementación en bruto en forma de un prototipo.

En segundo lugar, en el modelo abierto las partes interesadas en cada etapa son diferentes. En el caso del modelo tradicional, las necesidades de la empresa (el caso de negocios) en última instancia, conducen el alcance y los requisitos de un proyecto; la fase de concepto está a punto de ponerse en piedra por el momento los ejecutores comienzan a participar. En el modelo de desarrollo abierto, la atención se centra más en general, el resultado deseado de los usuarios finales del producto. Los requisitos, e incluso los conceptos de alto nivel son más libres para evolucionar con el tiempo que el proyecto avanza.

El papel de la comunicación en el desarrollo de software

Los proyectos de software muy exitosos tienen éxito porque dan el nivel adecuado de atención a la comunicación clara de los conceptos y requisitos claves. Los expertos en ingeniería de software tienen diferentes opiniones sobre qué parte del esfuerzo total se debe dar a primeras fases de un proyecto.

Para hacer un proyecto abierto que se propone en la forma de un prototipo exitoso, es aún más importante tener en cuenta que los conceptos y requisitos deben estar bien documentados para la comunidad a un acuerdo sobre ellos. Hay varias razones para esto:

Los Ingenieros en proyectos de desarrollo tradicionales suelen ser geográficamente coincidentes, y utilizan formas de comunicación, tales como reuniones y sesiones de pizarra para llegar a decisiones y acuerdos. Los proyectos de desarrollo abiertos casi siempre están distribuidos geográficamente. El correo electrónico y las páginas web del proyecto, que son formas de comunicación, son típicamente las formas dominantes de la toma de decisiones y acuerdos; esto hace que una mayor precisión e integridad en una necesidad.

Al contrario que en el modelo tradicional en el que los grupos de interés son los jefes de productos, los proyectos abiertos tienen toda la comunidad (y los usuarios finales) como los actores. Si la comunidad no puede ponerse de acuerdo sobre los objetivos de alto nivel y los requisitos funcionales de un proyecto de software, el proyecto está condenado al fracaso desde el principio.

La documentación de conceptos, requisitos y Arquitectura

Los conceptos y requisitos comprenden la gran vista de los cuadros del proyecto de software. Estos definen aspectos como las principales capacidades del producto y el mercado objetivo previsto. La arquitectura define la entrada / salida de métodos, características de interoperabilidad, y la interfaz de usuario.

En las primeras fases de un proyecto los detalles aparentemente sin importancia, como la forma en que se reunieron los requisitos a menudo no se registran. Los intercambios de alto nivel realizados en la cartografía de los requisitos en la arquitectura a menudo no están bien documentados (en su caso).

Una trampa menos evidente en este punto es que los requisitos y la arquitectura se cuecen generalmente por los ingenieros de software experimentados con una idea buena, aunque incompleta, de los requisitos de los ejecutores. Por otro lado, los ejecutores son por lo general personas con menos experiencia, y tienen un enfoque más local - lo que significa que hay una oportunidad para la pérdida de la información inherente al traducir los requerimientos en las construcciones de software. Si un implementador no entiende cuan flexible es un requisito, o por qué el requisito esta allí en absoluto, la aplicación puede ser inadecuada o excesivamente limitada.

Este último efecto, se magnifica en el modelo de desarrollo abierto, donde los ejecutores no funcionan con el software como su trabajo del día; si lo hacen, a menudo no tienen el beneficio de años de experiencia en redes con los ingenieros dentro de una importante empresa de software. Si un proyecto de desarrollo abierto va a ser asumido por los ejecutores con menos experiencia, entonces la comunicación clara de los conceptos, las necesidades, y la arquitectura del software es de suma importancia.

La importancia de la documentación en el desarrollo de software

Para un programador una documentación fiable es siempre una necesidad. La presencia de la documentación ayuda a realizar un seguimiento de todos los aspectos de una aplicación y mejora de la calidad de un producto de software. Sus ejes principales son el desarrollo, el mantenimiento y la transferencia de conocimientos a otros desarrolladores. La documentación acertada hará que la información sea fácilmente accesible, proporciona un número limitado de puntos de entrada de los usuarios, ayuda a los nuevos usuarios a aprender rápidamente, simplifica el producto y ayuda a reducir los costos de soporte. La documentación se centra generalmente en los siguientes componentes que conforman una aplicación: entornos de servidores, reglas de negocio, bases de datos / archivos, resolución de problemas, instalación y despliegue de aplicaciones de código.

Entornos de servidor

La documentación detallada acerca de una aplicación y sus entornos es siempre una necesidad. Esta información le ayudará con la creación de nuevos entornos para su aplicación y se debe presentar la ubicación y función de los sistemas que ejecutan sus servicios. Cosas que deben ser especificados aquí son el nombre de la aplicación / versión, el nombre del servidor, IP, directorio de código, la URL de la aplicación, el sistema operativo, información de la cuenta de usuario y un punto de contacto.

Reglas del negocio

La documentación de las reglas de negocio ayuda al equipo a adaptarse a nuevas incorporaciones más rápidamente, y a los hábitos de trabajo de la empresa. Proporciona información sobre cómo funciona el producto y por qué. La documentación de las reglas de negocio puede ser fácilmente compatible con los documentos de requisitos si están disponibles. Esto acelerará la curva de aprendizaje de un desarrollador de manera significativa. Además de las reglas de negocio, un documento de ayuda, preguntas frecuentes, o guía del usuario puede ayudar a resaltar los puntos principales de una solicitud de un desarrollador que necesita un contexto para la aplicación que están apoyando.

Base de datos / archivos

La información de base de datos es obligatoria. Es importante conocer el tipo de base de datos, la información del servidor, la versión pero lo más importante para tener un diagrama de modelo de datos. La documentación de la base de datos hará que el traer adiciones a la mesa, las modificaciones a la estructura y los tipos, las adiciones de índices y claves sea mucho más simple y más fácil de controlar y depurar. Además, si una aplicación presenta una funcionalidad de transferencia de archivos, se recomienda documentar en que forma se efectúa la transferencia, a través de qué protocolo y tipos de datos, y si SSL necesita certificados.

Solución de problemas

La documentación de la solución de problemas ayuda cuando se produzcan problemas de producción. La mayoría de los problemas técnicos deben tener los códigos de error que deberían ayudar a solucionar los problemas. En este documento también se debe incluir una sección de preguntas frecuentes para resolver los problemas más generales o habituales (tales como problemas de configuración). Los errores se deben documentar divididos por tipo de error, el módulo de dónde viene, y el nivel de error (excepción, advertencia, crítica, etc....).

Instalación de aplicaciones

Los Documentos de instalación y configuración son útiles para cuando los desarrolladores necesitan crear entornos nuevos o adicionales de aplicación. Si es posible, las medidas deben ser detalladas y fáciles de seguir y pueden incluir capturas de pantalla si es necesario. Cualquier persona debería ser capaz de seguir los pasos e instalar con éxito una aplicación. Tener los pasos identificados ayudará a prevenir al instalador problemas debido a la falta de piezas de una aplicación. Detalles como el software necesario, las bibliotecas y las versiones de servidor de aplicaciones, se pueden incluir para garantizar que el medio ambiente será compatible y configurado según lo previsto.

El Código

La documentación de código es la espina dorsal de cada aplicación. La documentación de código se puede dividir en varias partes. El primero de ellos, el más útil para los programadores son los bloques de comentarios. Estos se encuentran a través de todos los archivos que explica clases, métodos, parámetros posibles errores. Luego viene la documentación de archivos específicos. Estos normalmente se generan a través de una secuencia de comandos de terceros que analizar un archivo y, a partir de los bloques de comentarios, se creará un PDF explícito. Posteriormente debe haber información sobre el repositorio de código, donde se encuentran las actualizaciones de archivos, y donde tienen que ser movido. Además, no debe haber paso a paso las instrucciones sobre cómo crear un paquete de aplicación o una generación que se desplegarán.