Tutorial: documentación moderna con control de versiones

Koldo Aingeru Marcos

Uno de los puntos flacos en muchos proyectos de TI suele ser la documentación, bien la falta de la misma, su escasa calidad, poca coherencia o falta de actualizaciones. Muchas veces esto ocurre por no disponer de un sistema fácil para documentar y que sea fácilmente actualizable: ese archivo “.docx” enviado hace 3 meses por correo que se llama “documentacion_proyecto.ver2.revisado.final3.docx” no es aceptable.

Vamos a ver cómo lo solucionamos en una entrada más técnica de lo habitual.

Desde hace un tiempo, para poder mitigar este problema, existe una plataforma llamada Read the Docs (RTD); posiblemente ya hayas leído algo de documentación alojada en este servicio. RTD parte de una idea muy básica: la documentación tiene que ser accesible, fácil de leer, de estructurar y de editar. Nada del otro mundo, ¿no? Pero RTD no almacena la documentación como tal, simplemente la muestra a través del navegador. ¿Cómo funciona por detrás? ¿Podemos tener nuestro propio RTD dentro de la LAN?

Vamos a ver las partes que componen este sistema y cómo reproducirlo.

 

La documentación debe estar en un control de versiones

 

RTD funciona mediante la conexión a un sistema de control de versiones, que recoge la documentación (escrita en Markdown o Sphinx) y genera páginas HTML simples con el theme definido. El simple hecho de que la documentación tenga que estar en un control de versiones ya nos obliga a trabajar de cierta forma y ofrece grandes beneficios:

 

  • booksPoder otorgar permisos de edición a quien lo necesita.
  • Poder seguir los cambios realizados.
  • Tener copias de la documentación.
  • Necesidad de tener un procedimiento definido.

 

Una vez tenemos ya un sistema de control de versiones (Git es lo que usan los jóvenes hoy en día podemos usar Github o Gitlab) podemos pasar a escribir la documentación. Pero, ¿cómo lo hacemos?

 

El lenguaje de marcas

 

La documentación se tiene que poder editar en distintos sistemas, para lo que es necesario seguir un estándar. Uno de ellos es Markdown, que podemos escribir con cualquier editor de texto plano, ya que se basa en marcas (similar al HTML) que definen cómo es el texto: negritas, cursiva, tablas, enlaces, trozos de código…

Cualquiera que vaya a editar el documento puede hacerlo sin necesitar de un programa especial y esto ayuda a poder escribir documentación de forma más rápida. De hecho tanto Gitlab como Github interpretan Markdown en su interfaz web.

 

Generación de la documentación, la parte de la que se encarga RTD

 

typewritterUna vez que tenemos nuestra documentación escrita tenemos que generarla en un formato más sencillo para poder leerla y que esté disponible para todo el mundo; esta es la parte de la que se encarga RTD. Simplemente habría que darse de alta, asociar el repositorio y publicarlo.

El problema viene cuando no queremos que la documentación sea pública o esté disponible para todo el mundo, para lo que hay varias opciones:

La primera y a priori más sencilla es usar la versión de pago de RTD, claro que si nos queremos evitar el coste de la misma la segunda opción es la de montar un servidor de RTD in house, en nuestro propio hardware o cloud interno. Al ser de Open Source o de código abierto está disponible tanto el código como las instrucciones para montar nuestro propio RTD. Sin embargo y tras haberlo probado, he de decir que se trata de un proyecto muy grande que quizá suponga matar moscas a cañonazos ya que tiene bastante mantenimiento asociado.

Una opción bastante buena es usar Mkdocs. Se trata de un software escrito en Pyhton que en su momento fue el motor de RTD: a partir de una carpeta de Markdown genera otra con el sitio en HTML, pero con la diferencia de que se hace con un simple comando. En Sarenet la usamos internamente para generar, por ejemplo, la documentación a clientes de nuestro servicio de Centralita Virtual.

Vamos a ponernos manos a la masa y ver cómo se hace utilizando esta documentación como ejemplo.

manos a la masa

Para este ejemplo no necesitamos que la documentación esté en Git ni nada similar, si bien es muy recomendable como he señalado anteriormente. Al tratarse de un programa en Python, podemos instalarlo usando Pip si estamos en Linux o Mac OS X (como es mi caso), para Windows lo recomendado es usar Chocolatey.

 

Un ejemplo práctico para comprenderlo mejor

 

Mkdocs necesita de una estructura concreta de carpetas:

  • Un archivo “mkdocs.yml“, un archivo en YAML con la estructura de la documentación, el tema a usar, etc.
  • Una carpeta “docs“, dentro de la cual irán los archivos de la documentación con extensión “.md

En nuestro caso:

velaciela:centralita-documentacion-clientes koldo$ ls -la
total 16472
drwxr-xr-x 13 koldo staff 442 19 feb 11:27 .
drwxr-xr-x 21 koldo staff 714 16 ago 12:22 ..
drwxr-xr-x 16 koldo staff 544 19 feb 11:27 docs
-rw-r--r--@ 1 koldo staff 1373 29 jun 15:44 mkdocs.yml

Y el contenido del archivo “.yml“:

site_name: Centralita Sarenet
markdown_extensions:
 - admonition
theme: readthedocs
pages:
- 'Introducción': index.md
- 'Panel de gestión': panel_de_gestion.md
- 'Extensiones': extensiones.md
- 'Telefonos': terminales.md
- 'Fabricante':
 - 'Cisco': terminales/cisco.md
 - 'Yealink': terminales/yealink.md
 - 'Panasonic': terminales/panasonic.md
- 'Configuración de entrada': configuracion_de_entrada.md
- 'Configuración de salida': configuracion_de_salida.md
- 'Aplicaciones':
 - 'Bloqueo de llamadas' : aplicaciones/bloqueo_de_llamadas.md
 - 'Buzón de voz' : aplicaciones/buzon_de_voz.md
 - 'Call Center' : aplicaciones/call_center.md
 - 'Día / Noche': aplicaciones/dia_noche.md
 - 'Directorio compartido': aplicaciones/directorio_compartido.md
 - 'Fax' : aplicaciones/fax.md
 - 'Grupos de salto' : aplicaciones/grupos_de_salto.md
 - 'Horarios y calendarios' : aplicaciones/horarios_y_calendarios.md
 - 'IVR' : aplicaciones/ivr.md
 - 'Locuciones y grabaciones' : aplicaciones/locuciones_y_grabaciones.md
 - 'Música en espera' : aplicaciones/musica_en_espera.md
 - 'Registro de llamadas' : aplicaciones/registro_de_llamadas.md
 - 'Sala de conferencias': aplicaciones/salas_de_conferencias.md
- 'Estado': estado.md
- 'Códigos especiales': codigos_especiales.md
- 'Glosario': glosario.md 
- 'Acerca de': acerca_de.md

Y luego cada archivo “.md” es un archivo de texto normal:

cat docs/index.md 
![logo_sarenet](/img/logo_sarenet.png)


## Secciones

La documentación está dividida en distintas secciones, primero una parte general sobre los terminales para terminar explicando las distintas aplicaciones y funciones de la centralita

* Acceso al panel de gestión
* Extensiones
* Terminales
* Configuración de entrada
* Configuración de salida
* Aplicaciones y configuración extra
* Códigos especiales

Estas secciones obedecen a la forma en que la centralita está diseñada internamente.

Una vez lo tenemos podemos ver cómo quedaría la documentación con el comando “mkdocs serve“. Cuando veamos que es correcto usamos el comando “build” para generar el HTML.

velaciela:centralita-documentacion-clientes koldo$ mkdocs build --clean
INFO - Cleaning site directory 
INFO - Building documentation to directory: /Users/koldo/Proyectos/git/centralita-documentacion-clientes/site 
velaciela:centralita-documentacion-clientes koldo$

documentacion generadaDe este modo generamos la carpeta “site” con HTML, que podemos subir a cualquier servidor interno (o público) y visualizarla en cualquier navegador.

Al usar el tema de RTD además tenemos el menú lateral con el buscador y el índice de contenidos, generado automáticamente a partir de la estructura del archivo “.yml“.

En la imagen del lateral se puede apreciar cómo el texto es el mismo del ejemplo que he puesto arriba y cómo el menú lateral tiene la misma estructura.

Adicionalmente, mediante el uso de herramientas como Pandoc, se podría llegar a convertir a PDF pero cuando he hecho pruebas no me ha mantenido el mismo orden en las secciones que tenía el original.

Al poder generarse de una forma tan sencilla es muy simple y fácil añadirlo a nuestro script de deploy y automatizarlo con cada versión que escribamos.

Posiblemente te haya surgido la pregunta “¿Y qué tiene de malo una wiki?” En efecto una wiki es una opción muy aceptable de documentación si se mantiene organizada, y precisamente ese es el problema. Cuando generamos una nueva página en una wiki no tenemos necesidad de enlazarla en ningún sitio y puede quedarse en el olvido, además de que por lo general suele ser necesario que alguien se encargue de su mantenimiento. En cambio, con un sistema como este todos los contenidos están visibles desde un primer momento.

 

Contacta ahora con Sarenet

 

Sobre este Autor

Administrador de Sistemas en Sarenet.

1 Comentario

Puedes enviar comentarios en este post.

Enviar una respuesta

No hay comentarios