Tipos de documentación

Documentación interna de desarrollo

Especialmente la documentación del código, para que uno mismo y otros programadores entiendan lo que hace y por qué lo hace.

Suele ser una tarea tediosa. Y aún hoy existe controversia sobre la necesidad de comentar el código o no. Pero seguir buenas prácticas de documentación facilita el mantenimiento de los proyectos, la corrección de errores y el escalado de las aplicaciones.

También puede haber archivos de documentación interna en el propio repositorio del proyecto, como:

El archivo README
Explicando el propósito del proyecto, cómo instalar, utilizar o también sobre cómo colaborar.
El archivo CHANGELOG
Con los cambios relevantes publicados en cada nueva versión del software.

Documentación de seguimiento del proyecto

Como los requerimientos iniciales, el plan de proyecto, los informes de seguimiento, la gestión del cambio, o las actas con las decisiones acordadas por los diferentes comités de trabajo.

También se incluye aquí la documentación técnica de las fases de análisis y diseño como los diagramas de clases, los casos de uso, etc…

Documentación para el usuario final

Incluyendo las instrucciones de instalación y configuración si es un proyecto llave en mano, manuales de ayuda, o también:

Tutoriales

Orientado al aprendizaje
Permite a las personas introducirse
Es una lección

Por ejemplo: enseñar a cocinar a un niño

Guías CÓMO-HACER (HOW-TO)

Orientado a resultados
Muestra cómo resolver una necesidad concreta
Una serie de pasos

Por ejemplo: una receta de cocina concreta

Explicaciones de uso

Orientada a entender
Explica
Ofrece contexto

Por ejemplo: un artículo sobre la historia social culinaria

Guías de referencia

Orientada a informar
Describe cómo está construido
Es exacto y completo

Por ejemplo: una entrada de la enciclopedia

¡Cuidado con el exceso de documentación! No son pocos los que han alertado sobre el impacto negativo (económico, productivo, motivacional, etc.) del exceso de documentación.