Ad Clicks :Ad Views : Ad Clicks :Ad Views :

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,:

  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.

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

Leave a Comment

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

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.

This div height required for enabling the sticky sidebar