Newsletter para devsEntra
Web Reactiva

WR 62: Tu documentación miente y lo sabes

La documentación es una parte muy importante del desarrollo de cualquier aplicación de software. Pero a veces no ponemos todo el cariño que debiéramos en ella.

Escúchalo también en Spotify | Apple Podcasts | Google Podcasts | iVoox

Antes de empezar recordaros que sigue en marcha la recopilación que estamos preparando para el Calendario de Adviento del Código Libre.

Habéis enviado referencias sobre editores de audio, gestores de contraseñas, ERP’s… Todo software libre o de código abierto. ¡Muchas gracias por participar! :)

También continuamos con la cuarta entrega del #desafíoPython, esta vez con programación orientada a objetos y JSON como protagonista. Ya queda menos para tenerlo resuelto.

Documentación funcional

Da igual que sea para un producto propio, un proyecto para la administración o un proyecto de software libre. No puedes dejar la documentación en manos de preguntas sueltas en stackoverflow.

Getting started” o empieza aquí.

La descripción más sencilla posible para verlo funcionar. Esto te ayudará ya a ser mejor programador. Porque tienes que hacer que tu sistema funcione a la primera, siempre, y en las menores líneas posibles.

De hecho cada página web es un software y siempre deberíamos tener algo como un “empieza aquí”.

Instalación.

Puede haber más de una forma de instalar tu aplicación, debe quedar explicada para cada plataforma. Si es un autoinstalable, podrías dar opciones para que puedan complicar el código .

Guía de referencia.

Hereda de la documentación que nace del código o de la API del software. Se detalla la funcionalidad lo mejor estructurada posible. Con ejemplos de código, mejor aún si es ejecutable. Cada elemento de nuestro sistema debería tener un apartado.

Algunos ejemplos buenos son la documentación de Laravel o Stripe.

Documentación de Stripe

Dirígete siempre a un perfil concreto, el lenguaje lo es todo. Casos como el de Drupal Commerce distinguen entre el usuario con rol programador, el gestor e incluso el usuario que ejecuta la compra.

Manuales y tutoriales.

Si sabemos que nuestra aplicación está diseñada para cubrir una necesidad, explícala en forma de tutorial, dando detalles al que lo lee de cómo debe usarla. No sólo me refiero al aspecto técnico, también a configuración o a como sacarle provecho como usuario.

Puedes emplear vídeos, no solo para la presentación de la aplicación, también para explicar procesos complejos. Es más divulgativo, aunque no debes olvidarte del texto escrito.

Por propia experiencia te digo que mejorará tu código, ya que te darás cuenta que determinado proceso es demasiado dificil y lo simplificaras. Ponte siempre que puedas en el mismo plano que quien va a usar tu software.

Preguntas frecuentes o FAQ

No pueden resolver como funciona todo el sistema, pero a veces hay preguntas muy concretas que se repiten de forma constante. Y si, las tendrás respondidas en otra parte, pero bien sabemos que la solución a veces está escondida.

Cookbook o libro de recetas,

Es la ampliación de las FAQ pero para casos técnicos concretos. Una receta que, copiada y pegada, puede resolver muchas horas de trabajo. Quizás no sea lo más fino, pero la satisfacción de nuestros usuarios es lo más importante.

Documentación guiada por errores.

Se sale de lo anterior, pero es quizás, la primera que sufre el usuario. Cuando se produce un error explica lo que ocurre. Y si no está claro, indica un código de error para darle seguimiento cuando te pregunten o busquen.

Buenas prácticas en documentación

  • Piensa para quién es la documentación, cada una responderá las preguntas de usuarios con perfiles diferentes (programador, usuario, cliente, gestor).
  • Mantenerla actualizada es más complicado incluso que redactarla por primera vez.
  • Vívela como un contenido activo, no como una carpeta con anillas que metes en un cajón.
  • Muchos llegarán por la funcionalidad, pero se quedarán por la documentación.
  • Lo importante no es la herramienta con la que lo ejecutes, sino la facilidad que tenga de uso esa herramienta para que no sea un obstáculo.

Enlaces del programa

Herramientas para gestionar documentación:

Artículos sobre el tema

Enlaces del feedback sobre Blockchain

Puedes seguir a Web Reactiva en el canal de telegram t.me/webreactiva o en la cuenta de twitter @webreactiva con referencias, recursos y enlaces de interés.

Escrito por:

Imagen de Daniel Primo

Daniel Primo

CEO en pantuflas de Web Reactiva. Programador y formador en tecnologías que cambian el mundo y a las personas. Activo en linkedin, en substack y canal @webreactiva en telegram

12 recursos para developers cada domingo en tu bandeja de entrada

Además de una skill práctica bien explicada, trucos para mejorar tu futuro profesional y una pizquita de humor útil para el resto de la semana. Gratis.