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.
Recuerda la propuesta de documentar software que te proponía para los proyectos en Scrum. 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/