Un programa de computadora es un mensaje de un hombre a una máquina. Pero un programa escrito tiene otra cara, la cual le cuenta la historia al usuario humano.

Se requieren diferentes niveles de documentación para el usuario casual de un programa, para el usuario que depende de un programa y para el usuario que debe adaptar un programa para cambios.

Cada usuario necesita una descrición en prosa del programa. Para escribir una descripcion en prosa util, debemos tomar en cuenta los siguientes puntos:

1. Propósito.
2. Ambiente.
3. Dominio y rango.
4. Funcinoes realizadas y algoritmos utilizados.
5. Formatos de entrada-salida.
6. Instrucciones operativas.
7. Opciones.
8. Tiempo de corrida.
9. Presición y pruebas.

Esta información se puede hacer normalmente en tree o cuatro páginas.

La descripción de como será usada debe ser suplementada con alguna descripción de como sabemos que esta trabajando. A esto se le conoce como casos de prueba.

Adaptar o modificar un programa requiere considerablemente mucha información. El modificador necesita una visión general clara de la estructura. Los compotentes de esta visión general son:

1. Un diagrama de flujo o grafo de estructura de subprograma.
2. Descripciones completas del algoritmo usado.
3. Una explicación de la disposición de todos los archivos utilizados.
4. Una visión general de la estructura de paso.
5. Una discusión de modificaciones contempladas en el diseño original.

El diagrama de flujo es la pieza de documentación mas sobrevendida a fondo. Muestra la estructura de desición de un programa.

Los diagramas de flujo son más exhortados de lo que son practicados. Es muy poco visto que se escriban diagramas de flujo antes de escribir los programas.

Un principio básico de procesamiento de datos muestra que intentar mantener archivos independientes en sincronismo es una tontería. Es mucho mejor combinarlos en un archivo y cada registro conteniendo toda la información de ambos archivos.

Para un método de documentación,la primera noción es usar partes del programa que tienen que estar ahí de cualquier manera, para tener tanta documentación como sea posible. Una segunda noción es usar formatos tanto como sea posible. La tercer noción es insertar la documentación en prosa necesaria en el programa como párrafos de comentarios.

Algunas técnicas de auto-documentación son::

1. Usar un nombre de trabajo separado para cada corrida, y mantener una bitácora mostrando que se ha intendado, cuando y los resultados.
2. Usar un nombre de programa que sea un mnemónico y que también contenga un identificador de versión.
3. Incorporar la descripcion en prosa.
4. Referirse a la literatura estándar para documentar los algoritmos.
5. Mostrar la realción al libro del algoritmo.
6. Declarar variables.
7. Marcar el inicio con una etiqueta,
8. Etiquetar las sentencias en grupos para mostrar las correspondencias en la descripción del algoritmo.
9. Agregar flechas de flujo lógico a mano al listado.
10. Usar lineas de comentarios o remarcar cualquier cosa que no parezca obvia.
11. Poner sentencias multiples en una línea.

El método de auto-documentación está estimulado por el uso de lenguajes de alto nivel. Puesto que las máquinas están hechas para las personas, no las personas para las máquinas, su uso hace cada sorma de sentido, económico y humano.