DOCUMENTACION SOFTWARE (23828)

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.