La importancia de la documentación en proyectos de software

La documentación oficial es algo en lo que dependo a diario debido a mi profesión. Como la mayoría de mis escritos son de naturaleza tutorial, considero que esa documentación es un estándar que me guía. Sin esa documentación, tendría que arreglármelas por mi cuenta para entender todo. En algunos casos, eso no es tan malo. Pero en otras ocasiones, la documentación oficial simplemente no es suficiente.

La realidad es que no toda la documentación es igual. Y si he aprendido algo en los últimos cinco años, es que depender de la documentación oficial es como depender de un zapato para hacer el desayuno.

En pocas palabras, el zapato no puede cocinar y la documentación te va a fallar.

Eso es un gran obstáculo para muchos proyectos de cualquier tamaño. Pero cualquiera que haya tenido que utilizar documentación oficial entiende que la lucha es muy real. La documentación oficial está desactualizada, rota o simplemente falta. Para empeorar las cosas, en muchos casos es tu responsabilidad descubrirlo por ti mismo.

¿Por qué falla la documentación?

Aunque esto puede que no sea tu primera pregunta cuando te encuentras con una documentación deficiente, es necesario hacerla. He descubierto que existen algunas razones por las cuales la documentación falla en una comunidad. Con ciertos programas (como Kubernetes), los proyectos evolucionan tan rápido que los responsables, empleados y voluntarios no pueden mantenerse al día. Cuando eso sucede, lo primero que se abandona es la documentación. Esto es problemático, especialmente cuando una nueva versión rompe las funcionalidades de las iteraciones anteriores. No puedo contarte la cantidad de veces que he tenido que recurrir a la documentación oficial de Kubernetes, solo para descubrir que no funciona. Esto ha ocurrido tan frecuentemente, que ni siquiera me molesto con la documentación oficial. En su lugar, intento resolver el problema por mi cuenta o busco en Mastodon u otro servicio donde usuarios del producto puedan haber solucionado el problema.

Otra razón por la cual esto ocurre es que un proyecto simplemente no cuenta con personal suficiente para ocuparse de la documentación. En esos casos, la documentación comienza siendo muy escasa y se va incrementando con el tiempo. Pero eso no ayuda a los primeros adoptantes o a aquellos que actualizan tan pronto como la nueva versión está disponible.

Cómo instalar podman-compose en AlmaLinux 8 y 9

Otra razón más es que los responsables del proyecto crean su herramienta únicamente para uso interno, no se molestan en escribir documentación y eventualmente lanzan el software al público (olvidando que nunca hicieron la documentación en primer lugar).

Todas estas razones señalan lo que llamo la deterioración de la documentación. A menos que se actualice con regularidad, la documentación se deteriora y (eventualmente) se vuelve inutilizable. Esta situación no es sostenible.

Importancia de una buena documentación

En pocas palabras, cuando la documentación se deteriora, los usuarios, administradores y desarrolladores tienen dificultades para utilizar un producto. O peor aún, esas mismas personas no tienen más opción que buscar en otra parte. En algunos casos, no hay otra parte, por lo que esos usuarios no tienen más remedio que hacer lo posible para entender cómo hacer que las cosas funcionen.

Es ahí donde me encuentro regularmente, luchando para hacer que algo funcione. Y esto ocurre todo el tiempo. Afortunadamente, tengo más de 20 años de experiencia en esto, por lo que hacer funcionar una documentación deficiente es algo natural para mí. Desafortunadamente, no todos tienen esa experiencia. Y cuando un usuario, administrador o desarrollador se enfrenta nuevamente a una documentación deteriorada, la frustración que les acompaña puede ser abrumadora (especialmente cuando tienes al equipo directivo presionándote para poner algo en funcionamiento).

Esto se convierte en un problema especialmente importante en el software de código abierto, donde los usuarios no tienen una empresa a la que acudir para recibir soporte. Y dado que muchos proyectos de código abierto pueden tener dificultades para atraer suficientes voluntarios que mantengan la documentación al día, este problema se vuelve aún más pronunciado.

¿Qué se puede hacer para evitar la deterioración de la documentación?

En primer lugar, los proyectos grandes deben dar una mayor importancia a la documentación. Esto debería ser algo evidente. Y en lugar de depender de que los desarrolladores escriban la documentación (porque los desarrolladores no siempre son los mejores para explicar algo en un nivel de usuario final o administrador), esos proyectos deberían considerar contratar un equipo de documentación como una necesidad. Sí, esto tendrá un costo asociado, pero el impacto de tener una documentación que funcione y sea fácil de seguir se medirá en la lealtad a la marca y el crecimiento continuo.

Comparación de características: ServiceNow vs. Jira Service Management

Para proyectos más pequeños (que no pueden permitirse o atraer a un equipo dedicado de documentación), utilizar voluntarios es una necesidad. Pero muchos proyectos más pequeños tienen dificultades con esto. No solo no han establecido el proceso para crear una documentación efectiva, sino que también pasan la mayor parte de su tiempo de reclutamiento buscando desarrolladores. Esos proyectos más pequeños deben priorizar la creación de un equipo que se asegure de que la documentación sea coherente, esté actualizada y, simplemente, funcione. Las redes sociales son una excelente forma de encontrar a esas personas, pero requiere tiempo y esfuerzo. La recompensa por tu esfuerzo será evitar la deterioración de la documentación y tener usuarios más satisfechos.

Hasta que esto suceda, los usuarios, administradores y desarrolladores seguirán luchando para integrar o utilizar tu proyecto. Cuando eso ocurre, esos usuarios potenciales se alejarán y buscarán otro proyecto. ¿Puedes permitirte eso (junto con la posible mala reputación que podría acompañar a tal evento)?

Ya es hora de que la documentación se convierta en un elemento igual de importante que el código del proyecto. Hasta que eso suceda, asume que con cada actualización que lances algo se romperá en tus tutoriales, instrucciones de lectura y documentos.

Suscríbete a Newsmatic's How To Make Tech Work en YouTube para obtener los últimos consejos tecnológicos para profesionales de negocios de Jack Wallen.

Los mejores cursos en línea para mejorar tus habilidades de desarrollo en Python

En Newsmatic nos especializamos en tecnología de vanguardia, contamos con los artículos mas novedosos sobre Desarrollo, allí encontraras muchos artículos similares a La importancia de la documentación en proyectos de software , tenemos lo ultimo en tecnología 2023.