Un nuevo post de esta miniserie. La documentación de nuestro proyectos, aquí veremos como estructuro mi documentación para hacerla lo mas útil posible
Respecto a la estructura podemos decir que hemos visto algo a lo largo de estos posts, al final de la P[arte]0 vimos el template sugerido en writethedocs, en la P[arte]1 vimos varios enlaces con ejemplos de proyectos grandes y con eso podemos hacernos una idea de como ir estructurando nuestra documentación. Sin embargo en writethedocs podemos encontrar algunos enlaces útiles que nos ayuden aún más con la planificación de la estructura de nuestra documentación.
Dentro de los recursos que nos entrega la web y enfocado en este tema podemos decir que necesitamos que nuestra documentación cumpla dos requisitos que quizás no sea tan visibles al ver los ejemplos que hemos ido mencionando.
El primero de ellos es que la documentación debe ser precursora, esto quiere decir que debemos planificar la documentación incluso antes de empezar a escribir código o llevar nuestro proyecto a cabo, esto lo mencionamos también en la P[arte]0 donde, dentro de los beneficios de crear nuestra documentación esta el mejorar nuestro proyecto o código al lograr ordenar las ideas del proyecto o código.
Luego esta el hecho de que, para mejorar nuestra documentación esta debe ser participativa, lo que significa que mientras mas personas aporten a esta, mejor será, esto lo vimos en la P[arte]1 y esto también se puede traducir como:
«mientras más puntos de vista distintos tengas, mejor será tu documentación»
y por puntos de vista nos podemos referir a distintas necesidades dentro de nuestro «publico objetivo» o literalmente a más gente que nos este ayudando a crear nuestra documentación.
Por otro lado al momento de escribir tenemos que tener presente que la documentación debe ser localizable lo que significa que deberíamos colocar enlaces útiles en nuestra documentación en función de nuestros potenciales usuarios,
Descubrible
La traducción es un poco pobre pero a falta de un mejor sinónimo me quedo con descubrible.
¿A que hace referencia? pues muy simple, al hecho de crear caminos virtuales entre el usuario y mi publicación, entendiendo publicación como mi documentación.
El concepto que tienen que recordar es que si el usuario no lo encuentra no existe
Direccionable
Muy relacionado al punto anterior, debemos guiar a nuestro usuario por el mar de letras que es nuestra documentación, tratando de crear enlaces lo más granulares posibles para dar la oportunidad al usuario de ir directamente donde necesita ir
Completa
Este concepto también lo encontré un poco enredado, pero es bastante simple.
Completa no quiere decir que debo documentar todas las funciones que cumpla mi proyecto, aunque debería, sino que, si elegimos documentar la función A documentemos todo lo relacionado a la función A y no dejemos ningún detalle de esta función sin documentar
Bella
Con esto writethedocs nos dice que lo estético importa y una documentación no es la excepción, pueden ser cambios mínimos como por ejemplo la tabulación utilizada, lo que puede convertir una documentación en algo bello.
Como ejemplo para los que utilizamos Linux, no les ha pasado que ven el –help de algún comando y les da placer verlo? o al revés que prefieren ir al man para buscar el argumento que necesitan?
En el próximo post responderemos a la duda de ¿que debe contener mi documentación?
fuentes:
- https://www.writethedocs.org/guide/writing/docs-principles/#discoverable
- https://www.writethedocs.org/guide/writing/docs-principles/#addressable
- https://www.writethedocs.org/guide/writing/docs-principles/#cumulative
- https://www.writethedocs.org/guide/writing/docs-principles/#complete
- https://www.writethedocs.org/guide/writing/docs-principles/#beautiful