Documentación para clientes en markdown

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:

• Análisis de 3 editores de markdown gratuitos en mi blog
• Sublime Text con las extensiones Markdown Editor y Markdown Preview (Shareware)
• Visual Studio Code con extensiones (Open Source)

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.