Codificación aprenderaprogramar.com: CU00250A
DOCUMENTACIÓN PARA EL USUARIO
La documentación para el usuario constituye un elemento de consulta para toda aquella persona que va a usar el programa por primera vez o que trata de saber si el programa servirá a sus objetivos. Igualmente es útil para usuarios que ya realizan un manejo básico y quieren profundizar hacia un conocimiento avanzado. Una documentación completa contendría:
· Portada con el nombre del programa, versión y autor o autores.
· Índice.
· Descripción muy breve de las funciones y posibilidades del programa.
· Descripción breve del método de cálculo principal.
· Explicación breve de cómo debe usarse el programa y de los datos de entrada, opciones y resultados.
· Ejemplos paso a paso de uso del programa en número suficiente para comprender las posibilidades que se brindan.
· Diagrama de flujo del programa de carácter sintético y descriptivo.
· Especificación detallada de todas las opciones contenidas en menús.
· Especificación detallada de todos los cálculos, principales y secundarios.
La extensión de la documentación para el usuario será variable en función de la complejidad y características del programa: puede ir desde un párrafo para programas muy sencillos y de fácil uso hasta centenares de páginas para programas comerciales complejos. Los puntos contenidos en la documentación también son variables, siendo los enumerados anteriormente una orientación. Para programas sencillos puede reducirse a un título, una explicación breve del funcionamiento, entradas y salidas y un ejemplo de uso.
MANTENIMIENTO. DOCUMENTACIÓN PARA MANTENIMIENTO.
La documentación para mantenimiento constituye el elemento de referencia para el programador que haya de realizar cambios o ampliaciones del programa en el futuro. La necesidad de mantenimiento deriva de:
· Defectos del programa no detectados y que es necesario corregir.
· Cambios externos de índole política, técnica, social, etc. que afectan al programa: normativa, moneda, novedades de un sistema operativo, etc.
· Solicitudes de los clientes o usuarios.
El mantenimiento de un programa puede afectar a su esqueleto o diseño básico, a funciones importantes pero desligadas del núcleo del programa o a cuestiones meramente estéticas. De cualquier forma, el mantenimiento debe considerarse como programación en todos sus sentidos, debiendo partir del conocimiento del problema y avanzar con detenimiento siguiendo las normas para una programación sólida. Es ideal un mantenimiento que respete la filosofía y el estilo del programa que se mantiene, de modo que un auditor no pudiera detectar qué parte del programa corresponde al código original y qué parte a la ampliación o corrección.
Por desgracia esto muchas veces no se cumple, por descuido o porque simplemente realizar un mantenimiento de calidad puede ser muy costoso frente a una opción rápida y que funciona. El problema surge cundo diversas operaciones de mantenimiento con distintas formas de construcción y filosofía empiezan a afectar a la lógica e interconectividad entre las distintas partes del programa.
Veamos un símil gráfico:
No hace falta decir que si no se parte de un programa bien estructurado y comentado el mantenimiento se complica enormemente.
En ocasiones se renuncia a un mantenimiento de calidad comenzando un proceso de reparaciones puntuales rápidas. Cada reparación introduce un poquito de desorden y dificultad de seguimiento al programa hasta que se llega a un punto en que el mantenimiento es imposible o demasiado costoso. Es el punto en que “se nos cae” la estructura que hemos ido cogiendo con alfileres y en el que nos vemos obligados a desistir. Es el momento de hacer una reestructuración total o incluso de olvidarnos del código de que disponemos y empezar una nueva construcción.
No podemos decir que realizar un mantenimiento de calidad sea lo más adecuado: hay ocasiones en que puede interesar un mantenimiento rápido. El programador habrá de valorar varios factores, entre otros el tiempo disponible, las perspectivas de futuro del programa, etc.
Las casas de software dedican ingentes cantidades de recursos al mantenimiento de programas. A veces firman contratos con grandes clientes y les ofertan un mantenimiento adaptado a sus necesidades. En un año el programa puede avanzar de versión 6.30, 6.31, 6.32, ... correspondiendo cada una a los esfuerzos de las casas de desarrollo de software por mantener los programas con la máxima adaptación a los requerimientos del cliente.
Muchos programas de gran utilidad se pierden porque ya no existe mantenimiento para adaptarlos a los avances del hardware y los sistemas operativos.
Una documentación de mantenimiento completa puede contener:
· Portada, número de versión, autor.
· Índice.
· Objeto y aspectos principales del programa.
· Diagrama de flujo modular.
· Diagrama de flujo para cada módulo, desarrollado y con enfoque a las variables y procesos internos.
· Código completo del programa.
· Explicación de la gestión de errores del programa.
· Esquema o índice descendente del programa, actualizado.
· Explicación de variables, datos, archivos.
· Recomendaciones para el mantenimiento futuro.
· Cualquier información que se considere relevante para un programador que haya de trabajar con el programa.
Al igual que en el caso de la documentación para el usuario, la extensión y contenido de la documentación para mantenimiento será variable en función de la complejidad y características del programa. Para programas sencillos puede reducirse a un título, una explicación breve y unas recomendaciones, mientras que para programas comerciales puede requerir cientos de páginas repartidas en varios tomos.
Para acceder a la información general sobre este curso y al listado completo de entregas pulsa en este link: Ver curso completo.
Para hacer un comentario o consulta utiliza los foros aprenderaprogramar.com, abiertos a cualquier persona independientemente de su nivel de conocimiento.