DOCUMENTACION la documentación como ciencia documental se podría definir como la ciencia del procesamiento de la información, que proporciona información sobre algo con un fin determinado, de ámbito multidisciplinar o interdisciplinar. La documentación básica es necesaria ya que gracias a ella se puede, con rapidez y eficiencia: establecer una comprobación de propiedad localizar un objeto específico realizar un control del inventario establecer la identidad de un objeto relacionar la documentación con un objeto acceder a la documentación de manera eficiente y económica estimar el seguro DOCUMENTACION DE SOFTWARE Su documentación debería tener la siguiente estructura. 1. Requisitos La sección de requisitos describe el problema que se está solventando junto con la solución. 1.1 Visión general (hasta 1 página) Una explicación del objetivo del sistema y de la funcionalidad del mismo. 1.2 Especificación revisada. En esta sección debería aclarar tanto cualquier suposición que haya hecho sobre el significado de los requisitos, como cualquier extensión o modificación de los mismos. 1.3 Manual de usuario (1 - 5 páginas). Una descripción detallada sobre cómo el usuario puede utilizar el sistema, qué operaciones puede llevar a cabo, cuáles son los argumentos de la línea de comando, etc 1.4 Funcionamiento (1/2 página). ¿Qué recursos necesita el sistema para una operación normal y qué espacio y tiempo se espera que consuma? 1.5 Análisis del problema (2 - 10 páginas). En este se describe el modelo conceptual que hay detrás del diseño (y posiblemente la interfaz de usuario), si no se ha tratado ya. 2. Diseño La sección de diseño de su documentación proporciona un cuadro de alto nivel de su estrategia de implementación. 2.1 Visión general (1/2 - 3 páginas). Una visión general del diseño: organización de alto nivel, cuestiones de diseño especialmente interesantes, uso de librerías y otros módulos de terceros e indicadores de aspectos no resueltos o proclives al cambio 2.2 Estructura en tiempo de ejecución (1 - 5 páginas). Una descripción de la estructura del estado del programa en ejecución, expresada como un modelo de objeto de código 2.3 Estructura del módulo (1 - 5 páginas). Una descripción de la estructura sintáctica del texto del programa, expresada como un diagrama de dependencia entre módulos. 3. Pruebas La sección de pruebas de su documentación indica el enfoque que usted ha elegido para verificar y validar su sistema. Del mismo modo que no debería comunicar el diseño de su sistema presentando el código o incluso enumerando las clases, no debería únicamente enumerar las pruebas realizadas. 3.1 Estrategia (1 - 2 páginas). Una explicación de la estrategia general de las pruebas: blackbox y/o glassbox, top down y/o bottom up, tipos de test beds y manejadores de tests que se han utilizado, fuentes de datos del test, suites de prueba, métrica de cobertura, comprobación en tiempo de compilación frente a sentencias en tiempo de ejecución, razonamientos sobre su código, etc 3.2 Resultados del test (1/2 - 2 páginas). Resumen de qué pruebas se han realizado y cuáles no. 4. Reflexión La sección de reflexión del documento es donde puede hacer generalizaciones partiendo de éxitos o fallos concretos, hasta llegar formular reglas que usted u otros puedan utilizar en el futuro desarrollo de software. 4.1 Evaluación (1/2 - 1 páginas). Lo que usted considere éxitos o fracasos del desarrollo: problemas de diseño no resueltos, problemas de funcionamiento, etc. Identifique cuáles son los rasgos importantes de su diseño. 4.2 Lecciones (0,2 - 1 página). Qué lecciones ha aprendido de la experiencia: cómo podría haberlo hecho de otra forma una segunda vez, y cómo los errores de diseño e implementación pueden corregirse. 4.3 Errores y limitaciones conocidos. ¿De qué manera su implementación no llega a alcanzar la especificación? Sea exacto. Aunque perderá puntos por errores y características no presentes, obtendrá puntos parciales por identificar de manera exacta esos errores y el origen del problema. 5. Apéndice El apéndice contiene detalles de bajo nivel acerca del sistema, que no son necesarios para comprenderlo en un nivel superior, pero que se exigen para usarlo en la práctica o para verificar afirmaciones realizadas en cualquier parte del documento. 5.1 Formatos. Una descripción de todos los formatos adoptados o garantizados por el programa: para un fichero E/O, argumentos de la línea de comando, diálogos de usuario, formatos de los mensajes para las comunicaciones en red, etc. 5.2 Especificaciones del módulo. Debería extraer las especificaciones de su código y presentarlas por separado aquí. La especificación de un tipo abstracto debería incluir su visión general, campos de la especificación e invariantes abstractas. 5.3 Casos de prueba. Idealmente, su banco de pruebas lee tests de un archivo de casos de prueba en un formato que resulta cómodo de leer y escribir. No es necesario que incluya casos de prueba muy extensos. 6. Documentación del código Comentarios a nivel de especificación Tipos de datos abstractos. Cada tipo de datos abstractos (clase o interfaz) debería tener: 1. Una sección de visión general que dé una explicación de una o dos líneas sobre qué objetos del tipo representan y si son mutables. 2. Una lista de campos de especificación. Podría haber sólo uno; por ejemplo, un conjunto podría tener el campo elems representando al conjunto de elementos. Podría resultarle útil definir campos derivados adicionales que facilitaran la escritura de las especificaciones de los métodos; para cada uno de éstos, debería indicar que es derivado y explicar cómo se ha obtenido a partir de los otros campos Especificaciones del método. Todos los métodos públicos de las clases deberían tener especificaciones; los métodos privados complicados también deberían especificarse.