Un nuevo post de esta miniserie. La documentación de nuestro proyectos, aquí veremos distintas aproximaciones para empezar a crear nuestra documentación, dependiendo del contexto
Ya en el post anterior vimos la importancia de la documentación en cualquier tipo de proyecto, en este post veremos a quien debemos enfocar nuestra documentación
Como ya vimos anteriormente, debemos tener clara nuestra audiencia cuando escribamos nuestra documentación, también como el entorno donde sera requerida esta documentación, en writethedocs se distinguen 3 grandes grupos de entornos:
Desarrolladores de software Open Source
Gran parte de este entorno fue descrito en la P[arte]0, incluyendo un ejemplo, ahora veremos en detalle este ejemplo.
$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.
Como ven tenemos secciones bien definidas dentro de este archivo readme.md, que como comentamos anteriormente esta escrito utilizando el lenguaje de marcado Markdown
Como comentan en writethedocs, gran parte, o su totalidad, la realizamos sobre texto plano, por lo que los formatos de markdown y reStructuredText toman mucha relevancia y utilidad, en mi caso suelo utilizar Markdown.
La primera sección que podemos ver en el ejemplo es lo que pretendemos resolver con nuestro software, en este ejemplo el problema que pretendemos resolver es como documentar correctamente.
Continuamos con pequeños ejemplos de código, aquí podemos mostrar para que será usado nuestro código, en la web muestran el ejemplo de la librería Requests.
Podemos ver a continuación un listado de las características del proyecto.
Luego en este ejemplo, se muestran instrucciones de instalación, con lo básico basta, siempre podemos incluir enlaces a una página con más ejemplos, advertencias y sugerencias
La información de contribución nos permite informar a los usuarios como pueden apoyar al código, también podemos utilizar este apartado para comunicar como es que esperamos que funcione nuestro código, podemos encontrar un ejemplo en el proyecto Open Comparison.
La penúltima sección es para el soporte, aquí informamos cual y como será el canal de comunicación entre los desarrolladores y los usuarios para brindar asistencia Para esta sección se menciona el ejemplo de Django
La licencia en este ejemplo es la última sección, y permite a otros desarrolladores utilizar el código de acuerdo a la licencia que hayamos escogido
Una sección que quedó fuera de este ejemplo son las FAQ (Frequently Asked Questions) generalmente cuando nuestro proyecto lleva algún tiempo podemos ver que hay algunas preguntas que se repiten varias veces, podemos agrupar estas preguntas y su correspondiente respuesta en esta sección. Una advertencia que tenemos en la web es que esta sección suele quedar desactualizada por lo que es conveniente hacerle una revisión de vez en cuando. Como ejemplo mencionan el proyecto Tastypie
Desarrolladores en una compañía
Aquí entra en juego las políticas empresariales, hay empresas que tienen dentro de las funciones la creación de documentación, otras no, en el caso de estas ultimas debemos justificar la creación de esta documentación y es donde writethedocs se centra.
Como primer consejo desde writethedocs tenemos el empezar desde la ingeniería, o sea desde el mismo nacimiento del proyecto y junto al equipo de desarrollo
Luego el obtener inputs, esto lo conseguimos, entre otros métodos, organizando reuniones con todos los involucrados, asegurarse de mantener una discusión abierta y pública. Esto permitirá conocer todos los posibles casos de uso del código y obtener comentarios de todas las partes
Construir una taxonomía.
Taxionomía según la rae es la acción de clasificar, aquí básicamente debemos responder la duda de
¿donde coloco esto?
Idealmente, desde el inicio tener claro cada sección de la documentación, su propósito y que tipo de contenido contendrá, evidentemente posiblemente no podamos definir exactamente todas las secciones necesarias, pero ir adaptando la nueva información en secciones ya creadas o de ser necesario crear nuevas.
Recuerdo el principio KISS de archlinux y algunos proyectos más, Kiss significa Keep It Simple, Stupid!, en español ¡Mantenlo sencillo, estúpido! y esta relacionado a intentar utilizar herramientas ya conocidas por el equipo y hacer este nuevo proceso lo mas simple posible para evitar esa barrera del desconocimiento de herramienta no usadas comúnmente
Muy relacionado a la creación de taxiomas pero ya de forma mas «real», estableciendo la jerarquía de carpetas para cada tópico, para que todo el equipo sepa donde debe colocar cada recurso
Mantener al menos una reunión semanal para mantener un seguimiento del progreso, esto además brinda espacio para discutir ideas o problemas y también da la sensación que el proyecto avanza. Durante la implementación de la documentación estas reuniones sirven para planificar y hacer seguimiento, luego nos da el espacio para ir adaptándonos y obtener comentarios.
Los proyectos evolucionan, se agregan, eliminan o modifican funcionalidades y todas estas deberían estar en la documentación, junto con aplicar cambios de acuerdo a los comentarios que se hayan obtenido a lo largo de la vida de la documentación.
Usuarios empresariales
En esta categoría entran aplicaciones SaaS o empresas de servicios donde su publico objetivo son desarrolladores, en esta categoría la documentación juega un rol fundamental ya que una mala gestión de esta hará que los usuarios se vayan a otras aplicaciones.
Aquí vemos principalmente ejemplos de proyecto ya en funcionamiento que aplican todos los conceptos que hemos visto hasta ahora.
En este post respondimos en parte una de las dos preguntas que quedaron pendientes de la P[arte]0 ¿como estructuro mi documentación?, en el siguiente post veremos en detalle esta pregunta y la otra que es ¿que debe contener mi documentación?