Mencionar “documentación” en un proyecto es como decir “que viene el profe” en una fiesta.

Es un rollo, lo sé, pero tenemos que evitar poner obstáculos cuando generamos esa documentación aburrida y tediosa. Rara vez un desarrollador quiere dedicarle tiempo a esto, así que conviene ser muy efectivo y directo en su ejecución.

Al final del mensaje hay una parte más práctica, que espero te ayude

Desconozco si documentas o no o que requisitos tiene que cumplir ese material. A veces, para administraciones públicas, consiste en rellenar un formulario.

Luego otro.

Y otro más.

Aquí quedas atrapado en el espacio-tiempo y realmente no sabes si lo que estás rellenando ya lo escribiste antes.

Exagero, pero a veces parece que van a pillar.

Otras veces es un proyecto para un cliente o para el equipo de trabajo. Y la especificación técnica de cómo cumplimentar documentación no es tan exigente.

Al menos esa es mi experiencia.

Se nos abre una puerta para facilitar la tarea: markdown.

¿No sabes lo que es markdown?

Es un lenguaje de marcado para texto donde puedes asignar formato con algunos caracteres especiales. Por ejemplo colocar un texto entre asteriscos lo convierte en negrita.

El vincular el formato a algo tan simple a mi, en su día, me parecía llenar de caracteres raros un texto.

Ventajas del markdown

Salí pronto de mi error cuando vi las tres primeras ventajas:

  • Es un lenguaje universal. Al no tener código HTML, ni nada parecido, es seguro y por eso lo implementa desde telegram para los mensajes hasta los sistemas de anotaciones bancarias.
  • Es la base para generar documentos en cualquier otro formato: RTF, PDF, posts para blog…
  • Al ser ficheros planos el control de versiones (Git) te deja ver fácilmente los cambios introducidos.

Editores de markdown

Necesitamos entonces un editor con soporte para markdown. Hay infinitas alternativas, te dejo algunas aquí para que veas:

He utilizado todas estas opciones en algún momento.

La que contempla un editor de texto tradicional con extensiones de markdown puede ser la más propicia si quieres trabajar sobre la documentación como un proyecto propio con sus carpetas, imágenes y configuración.

El motivo no es otro que finalmente queremos crear una web navegable que sirva como documentación. Incluso como requisito nos hemos puesto que podamos distribuirla como un fichero ZIP con todo el contenido dentro.

¡Sacrilegio! Puede, pero también es práctico.

Nosotros haremos los deberes, con todos estos documentos en un repositorio remoto de proyecto, pero el cliente, muchas veces, quiere “poseer” lo que hemos preparado. Y es que una vez me dijeron:

Eso de estar en internet es como decir que tienes un castillo en el aire.

Cómo usar MKdocs

Vamos a lo práctico, a generar nuestra web “molona”. Hemos hecho referencia varias veces a los sitios estáticos. Pero nunca a Mkdocs.

Es una herramienta genial basada en python que con muy pocas líneas, teniendo la documentación organizada en carpetas, nos crea un sitio web navegable y entregable: no necesita servidor web.

Empezamos abriendo la terminal. Os dejo enlaces al principio del manual oficial de instalación, aunque creo que es sencillo seguir los pasos.

  1. Instalamos Python, si no lo teníamos previamente.

  2. Ahora ya instalamos Mkdocs con el gestor de paquetes de Python.

    pip install mkdocs

  3. Creamos un nuevo proyecto

    mkdocs new mis-documentos cd mis-documentos

  4. Escribimos un documento de prueba dentro de la carpeta docs con la extensión md. Más rápido es si nos bajamos un ejemplo, aquí directamente con curl.

    curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

En este momento tendremos esta estructura en la carpeta mis-documentos

├── docs  
│ ├── about.md  
│ └── index.md  
└── mkdocs.yml
  1. Abrimos el fichero de configuración mkdocs.yml y colocamos estos parámetros:
site\_name: Mis documentos  
nav:  
\- Inicio: index.md  
\- Info: about.md  
use\_directory\_urls: false

Bastante sencillo de entender todo, excepto el último parámetro. Es con el que vamos a conseguir que la página generada funcione tanto dentro de un servidor web como cargando en ìndex.html directamente en el navegador

  1. Último paso. Generar el sitio desde la terminal:

    mkdocs build

Si buscas en las carpetas ahora tendrás dentro de mis-documentos/site todo el sitio generado.

¿Fácil verdad?

Al menos la parte técnica, la de redacción de la documentación ya será otra cosa. Pero al menos el resultado te aseguro que es mantenible, escalable y reutilizable.

¡Mejor que un tetrabrik!

Puedes ver un repositorio de ejemplo con algunas opciones más de configuración.

¿Quieres ser mejor desarrollador?

Escrito por Dani

Soy programador web, podcaster y formador. Especialista en frameworks basados en PHP, aunque mis favoritos son los microframeworks en varios lenguajes (Python, Javascript) en los que constuyes de verdad a la medida la aplicación de tus sueños. Aquí puedes conocerme mejor.
comments powered by Disqus