Hablando de documentación P0

Navegando por la red me tope con la pagina https://www.writethedocs.org/ en un momento donde justamente en el trabajo están reclamando por una documentación que elaboré para uno de mis desarrollos así qué me dispuse a leer esta web y francamente la encontré muy interesante.

Esta guía será mi resumen de la documentación proporcionada por la web, iré colocando, como siempre, todas las fuentes al final del post por si les interesa profundizar en el contenido.

Las primeras preguntas que pueden surgir cuando hablamos de crear y mantener una buena documentación creo que son ¿para qué documentar? ¿quien leerá esta documentación? ¿que debe contener? ¿como estructuro mi documentación? entre otras

La primera pregunta ¿para que documentar? en mi caso es fácil de responder

A modo personal suelo llevar algunos scripts o desarrollos que una vez finalizados solo quedan ahí, funcionando sin más. La necesidad de documentar viene a surgir cuando luego de varios meses se debe realizar alguna modificación, en ese momento donde no recuerdo como fue que hice X o Y función y debo entenderla para realizar el cambio que necesito, este ejemplo también lo vemos en writethedocs, donde francamente me sentí aliviado cuando leí que no era el único al que le pasaba esto.

Para proyectos más grandes writethedocs nos ofrece una respuesta, además de la que ya les conté, añaden el hecho de querer que el usuario use nuestro código, suena extraño pero tiene lógica, si queremos que los usuarios utilicen nuestro código tenemos que «venderlo» e indicar que problema soluciona, como funciona y en que puede beneficiar a nuestro usuario y eso se puede hacer a través de la documentación ¿suena mas lógico ahora?.

Otro argumento que entregan es por el deseo de que nos ayuden con el desarrollo de nuestro código. Creo que este argumento es entendible más fácil que el anterior, si queremos por ejemplo que nos reporten fallos en nuestro código el usuario debe conocer donde y como hacerlo, lo mismo aplica a desarrolladores primerizos que nunca han contribuido con código en proyectos.

Para mejorar el código. Aunque suene raro el hecho de pasar de una idea directamente a código haciendo realidad la idea a veces puede ser desordenado, sin embargo al plasmar la idea en la documentación nos permite estructurar de mejor manera la idea y esclarecer el código que escribamos además de ver de forma más clara el diseño de la arquitectura lo que se traduce en una mejora en el código en comparación a si lo hubiésemos escrito directamente desde la idea

La siguiente pregunta, ¿quien leerá esta documentación? En general esta pregunta tiene 2 respuestas, aunque pueden haber casos donde existan mas respuestas

• Usuarios finales
• Desarrolladores

Las siguientes dos preguntas ¿que debe contener? Y ¿como estructuro mi documentación? Las veremos en los siguientes posts.

Finalmente en writethedocs nos pasan un template a modo de ejemplo, muy probablemente lo han visto en varios proyectos de gitlab o github. Ambas plataformas utilizan fuertemente el formato Markdown (próximamente una guía a mi estilo) para este archivo y es el que vemos sugerido en writethedocs junto con reStructuredText. El template nos brinda una estructura básica para empezar con la documentación de nuestro proyecto

$project
========

$project resolverá su problema de por dónde empezar con la documentación,
proporcionando una explicación básica de cómo hacerlo fácilmente.

Mira lo fácil que es de usar:

    import project
    # Haz tus cosas aquí
    project.do_stuff()

Características
--------

- Ser impresionante
- Hacer las cosas más rápido

Instalación
------------

Instala $project ejecutando:

    install project

Contribuye
----------

- Issue Tracker: github.com/$project/$project/issues
- Source Code: github.com/$project/$project

Soporte
-------

Si tiene problemas, háganoslo saber.
Tenemos una lista de correo ubicada en: project@google-groups.com

Licencia 
-------

El proyecto esta licenciado bajo la licencia BSD.