Una idea que me ha gustado sobre documentar software, es que hay 4 tipos que representan diferentes propósitos o funciones en la vida del producto Software,:

  1. Tutoriales
  2. How To Guides
  3. Explicaciones
  4. Referencias Técnicas

Tutoriales

Las tutoriales:

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

Analogía: enseñar a cocinar a un niño pequeño 

How-to guides

Una how-to guide:

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

Analogía: la receta concreta de un libro de cocina

Explicación

Una explicación:

  • Orientada a entender
  • Explica
  • Ofrece contexto

Analogía: Un artículo sobre la historia social culinaria

Referencia

Una referencia:

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

Analogía: referencia de una entrada en la enciclopedia

Documentación del proyecto

Si te preguntas donde está la gestión del cambio, el objetivo del proyecto o información semejante en este esquema, no vas a encontrar respuesta, puesto que eso no es estrictamente documentar software, es información del proyecto.

Lo mejor es mantener unos documentos y registros independientes para no mezclarlos, porque cuando quieres acceder a la documentación de los productos, la historia no es lo que más te preocupa, te preocupa el porqué está así.

Ref: https://www.divio.com/en/blog/documentation/