2. Una Documentación técnicamente es una pieza clave en la ingeniería de
software, para conocer cada importancia a través de los sistemas informáticos
adecuados y eficientes. pues los softwares deficientemente documentados son
difíciles de leer, más difíciles de depurar y casi imposibles de mantener y
modificar.
Puede ser interna y externa.
-La interna: Es la contenida entre las líneas de código (comentarios)
-La externa: incluye análisis, diagramas y/o pseudocódigos, manuales de
usuario con instrucciones para ejecutar el programa e interpretar los
resultados, así como los manuales de sistemas.
3. DOCUMENTACION INTERNA
Se trata de los comentarios que acompañan a cada subprograma (Rutinas):
Directorio: son comentarios que se sitúan al principio de los ficheros que
componen un programa e indican fundamentalmente los subprogramas
contenidos en dicho fichero. Por lo general esto comentarios incluyen la
siguiente información:
• Autor
• Fecha
Rutinas contenidas en el fichero y finalidad de cada una de ellas.
Son los comentarios que se colocan en cualquier lugar del código para explicar
partes del mismo. Pueden ser comentarios de una sola línea o bien de un cierto
número de ellas.
4. DOCUMENTACION EXTERNA
La documentación externa debe incluir:
Listado actual del programa fuente, mapas de memoria, referencias cruzadas,
entre otros
Explicaciones de formulas complejas.
Características:
Es útil para describir:
Como instalar y operar con el sistema.
Los requisitos y el diseño de todo el sistema.
5. DOCUMENTACION USUARIOS
Está diseñada para ser leída por el usuario del software, por consiguiente no
debe ser técnica.
Combinada con una interfaz de usuario bien diseñada hace un paquete de
software accesible.
MANUAL DE USUARIO
Sirve para educar al usuario acerca de las funciones del producto software
mientras le enseña a utilizarlo de manera efectiva.
Están dispuestos de tal forma que puedan leerse y consultarse fácilmente.
Debe crearse con un contenido efectivo y diseñado con la disposición adecuada.
6. DISEÑAR UN MANUAL DE
USUARIO LEGIBLE
FUENTES LEGIBLES: elegir un número reducido fuentes que se vean bien juntas.
Se pueden utilizar en grandes fragmentos de texto en tamaños de 8 a 10 puntos
en un documento impreso o digital.
LA DISTRIBUCION: colocar el titulo del manual o del capitulo en el encabezado;
el numero de pagina (en el encabezado o en el pie de página), diferenciando la
primera página de cada sección o capitulo de las otras paginas. Y dejar
márgenes razonablemente.
DISEÑAR UNA PLANTILLA DEL DOCUMENTO: muchos procesadores de texto
ofrecen la posibilidad de crear plantillas de documentos para los manuales de
usuario. La mayoría de estos programas también incluyen un conjunto de
plantillas predefinidas que puedes modificar según los necesites, en vez de
crear la plantilla desde el comienzo.
7. DOCUMENTACION DEL
SISTEMA
Es Muy importante que estos programas sean presentados en formato muy legible;
por esta razón se requiere un buen uso de la sintaxis y de la gramática del lenguaje
de programación de alto nivel. Así mismo se requiere seguir convenios de notación,
sangrados en las líneas de programa, establecer diferencias en la escritura de
nombres de variables, constantes, objetos, clases.
MANUAL DE MANTENIMIENTO Es ideal un mantenimiento que respete la filosofía y
el estilo original del programa, de modo que un auditor no pudiera detectar que
parte del programa, de modo que un auditor no pudiera detectar que parte del
programa corresponde al código original y que parte a la ampliación o corrección.
Una documentación de mantenimiento completa puede contener:
-Portada, numero de versión, autor, índice.
-Objeto y aspectos principales del programa.
-Diagrama de flujo modular.
-código completo del programa.