¡Documentar es tan viejo como los dinosaurios!

TL;DR En el proceso de creación de software hay una parte muy importante que todos olvidamos. La documentación del software, ya sea de cara del cliente o de cara al proyecto es muy importante, por eso hoy revisamos la herramienta Docusaurus que ayuda en poco tiempo a montar un blog, una landing y un sistema de documentación básico el cual una vez configurado no se necesita a un experto en programación para poder documentar el software.

Hola a todos! creo que concordamos que un problema de todo desarrollador o proyecto es que muchas veces olvidamos la documentación del software, y por mas que odiemos documentar es una de las fases mas importantes del ciclo de vida del software.

Una buena documentación evita mucho tiempo en soporte al usuario, evita tiempos muertos en explicar una y otra vés a nuevos usuarios o desarrolladores sobre las funcionalidades que ya se han realizado, e incluso a los propios creadores del código despues de mucho tiempo al no revisar dichas funcionalidades.

Screen Shot 2018-05-18 at 1.01.50 AM.png
docusaurus-pet

Por esta razón en uno de mis proyectos, comencé a utilizar Docusaurus, una herramienta de facebook muy divertida que te permite montar facilmente un sistema para que una persona (no necesariamente desarrollador) pueda comenzar con la documentación del proyecto muy facilmente.

¿Que lindo dinosaurio no?

¿Como iniciamos con la documentación?

Primero debemos instalar node/npm/yarn en nuestra máquina para ello vamos a nodejs.org e instalamos el paquete que vaya acorde a nuestro sistema operativo. Una vez hecho esto, ya tendremos instalado npm, que es el manejador de paquetes de Nodejs. Por mi parte prefiero un poco mas Yarn, que tambien es otro manejador de paquetes pero un poco mas “guay” y con algunas mejoras. les dejo el link de manera que puedan instalarlo y probarlo tambien.

entonces ya instalado el manejador de su preferencia (Yarn o NPM) vamos a la consola e instalamos docusaurus.

$ yarn global add docusaurus
$ npm install docusaurus --global

Perfecto con esto ya tenemos docusaurus instalado y cada uno de los binarios que necesitaremos para manejar docusaurus.

¿Y ahora?

Perfecto, ahora vamos al folder que queramos utilizar para nuestro proyecto y hacemos un :

$ docusaurus-init

Esto iniciará un nuevo proyecto, con 2 carpetas, una llamada docs-examples-from-docusaurus y una llamada website.

para hacer una prueba rápida de que mas tenemos, primero cambiaremos el nombre de la carpeta docs-examples-from-docusaurus a docs y luego entraremos a la carpeta website.

Dentro de la carpeta website encontramos un proyecto de react, y encontraremos otras carpetas que explicare ahora.

Screen Shot 2018-05-17 at 11.26.35 PM.png
docusaurus-arbol-tree

blog-examples-from-docusaurus: Esta carpeta contiene los post de ejemplo de docusaurus, para hacer la prueba vamos a cambiar el nombre de esta carpeta a “blog”

core: Esta carpeta contiene un archivo llamado Footer.js que nos permitirá modificar el componente utilizado por el footer del sitio.

package.json: El package.json es un archivo que contiene la información del proyecto de node, entre eso los paquetes que se deben instalar, el nombre del proyecto, la versión, entre otras cosas.

pages: En la carpeta pages encontramos los archivos users.js, help.js y index.js, estos archivos estan dentro de la carpeta en, que va un poco mas adelante para el manejo de las traducciones del sitio, pero que no cubriremos por ahora, lo importante son los archivos javascript que se encuentran dentro de ella.

static: La carpeta static son todos los archivos estaticos que se utilizarán dentro del sitio, imagenes, estilos, etc.

sidebars.json: En sidebars.json esta la configuración de como se generará el menú lateral de las páginas de documentación, allí organizaremos cada uno de los documentos de markdown que se encuentra en el folder “docs” al cual hemos cambiado de nombre anteriormente.

siteConfig.js: En este archivo tenemos varias variables de configuración, entre esas el nombre del sitio, la configuración del menú principal (superior), scripts extras que añadiremos al sitio, etc.

.gitignore: Por ultimo el script de inicio nos genera un archivo .gitignore con todos los folders que no se tendrán en cuenta si utilizamos git como sistema de versiones.

Es demasiado, ¡ya no recuerdo nada!

Tranquilos, iremos hablando de cada archivo, por ahora vamos a correr el sitio de ejemplo. Para correr este sitio nos ubicaremos dentro de la carpeta “website” y utilizaremos NPM o Yarn para iniciar nuestro proyecto.

$ yarn start
$ npm start

Al hacer uso de NPM/Yarn con la configuración start (pueden revisar el package.json para ver cual es el comando exacto que esto ejecuta) ya en nuestro puerto 3000 tendremos la página de muestra de docusaurus. y podrémos navegar en ella.

Screen Shot 2018-05-17 at 11.46.35 PM.png
docusaurus-example
Screen Shot 2018-05-18 at 1.03.19 AM.png
docusaurus-old-pet

Que feo dinosaurio, ¿no? :'(

Esperemos lo mejoren en una proxima entrega de docusaurus jeje.

¡Perfecto! ahora podemos comenzar a cambiar cosas

Si recuerdan, tenemos un archivo siteConfig.js, allí podemos comenzar a modificar los colores principales de nuestra página, vamos al objeto llamado siteConfig y buscamos la propiedad “colors”, allí hay 2 variables “primary_color”“secondaryColor”, si cambiamos estos colores veremos el resultado al reiniciar el servidor, por ejemplo:

Screen Shot 2018-05-17 at 11.57.01 PM.png
docusaurus-color-changes

Perfecto, pudimos cambiar colores, ahora que tal si vamos a la propiedad “title”, allí podemos cambiar el nombre del sitio, y además podemos cambiar la propiedad “tagline” con una corta descripción que queramos.

Tambien podemos jugar con los enlaces que aparecen en la parte superior derecha que es el menú principal, para ello modificamos el atributo “headerLinks”, para elló podemos cambiar a cuatro opciones diferentes.

headerLinks: [
    {href: 'https://google.com', label: 'Google'},
    {doc: 'doc4', label: 'API'},
    {page: 'help', label: 'Help'},
    {blog: true, label: 'Blog'},
  ]

La primera opción es un link externo, utilizamos el atributo “href” para el direccionamiento y label (que no cambia en las demas opciones) es que se presentará en el menú. La segunda opción es doc, esto envía directamente a un documento de los que se encuentran en la carpeta Docs, y el valor debe ser un ID de documento (mas adelante revisaremos esto), la tercera opción es una Page, en la cual podemos direccionar a un componente de react que se encuentre en el folder pages como por ejemplo “help.js”, el valor debe ser el nombre del archivo de javascript sin extención. Por ultimo  tenemos un link hacia el blog, el cual desplegará las entradas que se encuentran dentro de la carpeta blogs que se encuentra dentro de website.

recuerda cada cambio que realices en el archivo siteConfig.js debes reiniciar el servidor nuevamente.

Perfecto, veamos que mas podemos hacer.

¡Vamos por el index!

Otro archivo importante es el index.js, en este archivo encontraremos un conjunto (grande) de componentes que se encuentran en el landing page de nuestro sitio. y podemos modificar muchas cosas, por ejemplo, quitar imagenes, eliminar algunos componentes, cambiar el html, etc!.

Screen Shot 2018-05-18 at 12.27.56 AM.png
main-component-docusaurus

el componente principal, es el componente Index

acá podemos ver todos los componentes del index, un HomeSplash, un block para Features, otro para un callout llamado FeatureCallout, otro para learnHow y mostrar como usar la herramienta, un proximo “gancho” para que las personas prueben nuestra herramienta TryOut, otro para una descripción tal vez mas larga que las anteriores Description y por ultimo un modulo para mostrar los usuarios que ya usan nuestra herramienta Showcase. Estos usuarios pueden configurarse dentro del archivo siteConfig.js.

Con un poco de conocimiento extra de React (que no es el tema de este post por lo cual no ondare en detalles) podemos crear nuestros propios componentes y utilizar dentro de nuestra aplicación.

¡Y ahora, la documentación!

Si, ¡esta es la parte mas facil!, si alguna vez has utilizado markdown (tal vez con git y el famoso Readme.md) ya te puedes dar idea de como serán nuestros archivos de documentación, sin embargo explicaré un poco sobre ello.

Screen Shot 2018-05-18 at 12.35.44 AM.png
doc-example-docusaurus

Primero y muy importante vamos a colocar la metadata de nuestra documentación, en ella vemos el id, que debe ser unico por cada documento, este servira para identifcarlo dentro de nuestro archivo sidebars.json. El segundo atributo es el título de este documento, este se mostrará en grande en nuestra página, por ultimo queda el atributo sidebar_label que es el que se mostrará dentro del menú lateral. Estos datos deben estar enserrados entre tres guiones ( – ) arriba y debajo de ellos como se muestra en la figura.

Y luego, viene el documento en markdown, donde podemos crear links de la siguiente manera:

[nombre del link](url_del_link)

o podemos crear titulos de la siguiente manera:

# Título cabecera 1

## Título cabecera 2

### Título cabecera 3…

y así hasta 6 almuadillas, entre mas almohadillas mas pequeño sera el título (Si harás estrategias de SEO/SEM para tu página, te sugiero utilizar de dos almohadillas en adelante para no encontrar etiquetas <h1> dentro de tu codigo que pueden perjudicar tu estrategia de SEO).

al utilizar tripe acento (tílde) invertido ( `) podemos crear texto pre-formateado. la imagen anterior generará dentro de docusaurus una página como la siguiente:

Screen Shot 2018-05-18 at 12.45.53 AM.png
documentation-in-docusaurus.

Perfecto, y por ultimo, veamos la estructura de la metadata de un blogpost:

Screen Shot 2018-05-18 at 12.47.28 AM.png
blogpost in docusaurus

Al igual que en un documento, en un post tenemos metadata entre tres guiones ( – ) y son muy parecidos. El primer metadato es el título del blog, el segundo dato es el nombre del autor que se mostrará dentro del blogpost, por ultimo tenemos 2 datos el authorURL con una URL del autor, puede ser externa y por ultimo el ID de facebook del autor, estos dos ultimos datos no son requeridos pero ayuda a buscar información como foto o enviar a los lectores a una página externa donde se puedan comunicar con el.

Y con esto termminamos este review de Docusaurus una excelente herramienta para combinar programadores con documentadores, de manera que ambos solo se concentren en lo que mejor saben hacer, programar y escribir respectivamente. Esta excelente iniciativa de facebook hará que muchos pierdan el dolor de cabeza de escribir documentación poco atractiva para el usuario a llevar documentación de valor para todos.

Dejo el ejemplo aun un poco crudo en lo que he trabajado para que se vea que se puede ir cambiando con css y otros cambios menores. Un saludo y nos vemos en la proxima, muchas gracias 😁

This slideshow requires JavaScript.