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,:
- Tutoriales
- How To Guides
- Explicaciones
- 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/