En Sarenet empleamos soluciones Open Source o de código abierto siempre que existan dado que…
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.
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:
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?
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.
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.
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.
Mkdocs necesita de una estructura concreta de carpetas:
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  ## 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$
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.
Estamos observando una revolución silenciosa pero impactante, propiciada por el Internet de las Cosas (IoT).…
En un mercado inundado de opciones de servicio Cloud, las empresas deben decidir cuidadosamente cuál…
La Inteligencia Artificial (IA) uno de los temas más discutidos y fascinantes de nuestro tiempo.…
En un panorama empresarial marcado por una digitalización acelerada, la gestión de la información se…
Desde nuestros inicios hace 30 años, hemos observado de cerca la transformación de Internet, de…
Que vivimos una verdadera epidemia de ciberataques no es ningún secreto. La situación de hecho…