Documentar Software – La idea más fácil que conozco
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/
Herramientas para documentar software
Una de las obviedades siguientes a la que nos enfrentamos teniendo claro que es lo que necesitamos documentar de los productos software es la elección de una herramienta que automatice un poco todo.
A continuación os listo las herramientas para documentar software más populares que he encontrado:
Atlassian Confluence
Hoy en día, se puede decir que la herramienta para gestionar producto más utilizada es Jira de Atlassian. El propio fabricante tiene otro módulo muy interesante denominado Confluence que permite documentar los how-to y las referencias técnicas llegando a asociar Ticket de Jira- Documentación de código – Rama de Git (o Subversion).
Esto posibilita una visual del producto mucho más eficaz que ayuda a mantener un histórico de decisiones y una gestión de producto ágil.
Huddle
Orientado a organizaciones grandes donde todo esté en el mismo sitio.
Read the Docs
Plataforma gratuita en la nube para hacer una gestión documental de lo generado.
Javadoc
Elemento desarrollado para documentar las API de elementos Java creados
SWAGGER
Otra herramienta para documentar el flujo entero de desarrollo