Durante los años que llevo en el desarrollo de software todavía no he dado con la forma «perfecta» para ofrecer una documentación clara y eficiente para los usuarios de la aplicación.
Una documentación de usuario efectiva debería permitir :
- Resolver dudas sobre en que consiste la aplicación y cuales son sus características
- Encontrar solución a los problemas generales que pueda encontrarme
- Que tenga unos textos claros y concisos sin irse por las ramas
- Aportar una información extra a lo que pueda ver en la aplicación
- Consejos de como sacarle más partido a la aplicación
- Indexable por los buscadores
- Poder buscar por palabras internamente
Mantenimiento
Sin duda lo más complicado de una documentación de usuario es mantenerla. Un producto software esta vivo y se le van añadiendo funcionalidades, la documentación sea mucha o poca, debe ir actualizándose al mismo ritmo.
Elementos que van encontra del mantenimiento
- El tamaño. Cuanto más grande sea la documentación más dificil será tenerla al día. Menos es más
- Elementos gráficos, capturas de pantalla y vídeos son enemigos del mantenimiento, generalmente en poco tiempo quedan desfasados mostrando pantallas de versiones anteriores que confunden al usuario
- Descripciones exageradas de las pantallas (Ejemplo. Pincha en el botón azul redondeado a la derecha del texto nombre ) esas descripciones no aportan mucho valor pero al igual que las capturas quedan desfasados al cabo de poco tiempo cuando un cambio en el interfaz de las aplicaciones provoca que la descripción no detalle lo que realmente ve el usuario.
Buenas ayudas que conozco
Ayudas de Google
Google se esmera en no incluir capturas de pantalla, siempre lo explica con texto, lo que facilita su mantenimiento respecto los constantes cambios que van añadiendo.
Jenkins
Esta documentación tiene una buena división general ( Conoce, Usa, Extiende ) que permite ubicarte facilmente en que información necesitas.
davidgu 
¿Documentación? cuanta menos mejor.
Creo que se valora mucho porque se pide mucho por los usuarios… pero ¿la usan mucho? ¿es realmente valiosa?
Mi opinión: haz la menos posible, y pon el foco en los aspectos que más valor aportan, valor de verdad.
Muchos años llevo ya en el software, y mi experiencia no deja de confirmármelo: la mínima posible y Foco a otras cosas.
Gracias, David
Gracias por el comentario Santi!
El problema de mucha documentación es que luego no se podrá mantener.
Haz la documentación que puedas mantener
De nada vale tener un Ferrari si no tienes recursos para mantener una bici 😉