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:

  • Explicando el propósito del proyecto, cómo instalar, utilizar o también sobre cómo colaborar.

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.

Referencias

Última revisión: 25/06/2020

0 comentarios

Dejar un comentario

¿Quieres unirte a la conversación?
Siéntete libre de contribuir!

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *