Introducción a Asciidoc y Asciidoctor (2)

Este post es la continuación a intro-asciidoctor-1.html

Probablemente, tras leer el post anterior, te sigas preguntando por qué deberías usar asciidoc y su ecosistema como herramienta para tu documentación.

De forma resumida destacaría los siguientes puntos:

  • formato abierto

  • texto plano. Te centras en escribir y te olvidas de si las páginas encajan, si las imágenes de descolocan los parráfos, etc

  • versionable, revisable, mergeable por cualquier sistema de control de versiones

Todos ellos compartidos con Mardkown y otros. Pero además con asciidoc tienes:

  • una única sintaxis, a diferencia de los miles de sabores (incompatibles?) que tiene Markdown

  • un mismo texto puede generar diferentes outputs, como el típico caso de tener un .adoc y convertirlo a html y pdf

  • es semántico, está orientado a la documentación no a la presentación. Cuando lees asciidoc, lees el sentido que se le está dando a un parrafo (esto es importante, eso es un párrafo, esto es un ejemplo, etc)

  • un ecosistema supercompleto donde se han integrado multitud de herramientas: escribir fórmulas matemáticas en LaTex o AsciiMath, diagramas de secuencia, clase, actividades, grant,

  • al ser abierto existen muchos "backends": html, pdf, manpages, revealjs

  • si eres programador y usas Maven o Gradle, puedes integrarlo en tu proyecto fácilmente

Casos de uso

Estos son algunos casos de uso donde yo lo he usado (no es por autobombo, es que así me ahorro tener que citar autores):

  • Artículo

Presentar una redacción o un artículo corto para la universidad.

  • Trabajo Fin de Grado

Presentar algo más complejo que una redacción, con capítulos, revisión de historial, diagramas, fórmulas, etc

  • Documentar un proyecto

Documentar un proyecto, explicando funcionalidades, ejemplos, etc,

  • Página comercial de una empresa

Crear la landing page de una empresa/producto

  • Un blog

Este mismo, por ejemplo, sin necesidad de bases de datos, editores complejos, etc y alojado sin coste en cualquiera de los numerosos sistemas que ofrecen páginas estáticas

  • Blog multiformato

Este blog publica en html, pdf y epub el mismo contenido

  • Presentación de una charla

Uso de RevealJs para presentar la charla y después se exporta a SlideShare para compartirlas

Slides:

  • Libro digital en Amazon

Puedes usar el backend de ePub para generar un libro compatible con la plataforma de publicación de Amazon

(tengo pendiente hacer una revisión y publicarlo actualizado)

Ventajas

Al ser sólo texto puedes editarlo desde muchos dispositivos y situaciones. Por ejemplo he revisado y corregido numerosos errores desde el metro con el móvil e incluso al tener el proyecto integrado con un proceso de despliegue contínuo, llegar a publicar las correcciones directamente.

Como ya he comentado anteriormente, al centrarte en lo que quieres decir y no en cómo va a quedar te vuelves más productivo. No te engaño, en tu primer intento vas a querer cambiar la presentación del documento y te vas a desesperar porque no es fácil.

Al poder integrarlo en la construcción de un producto (no hace falta que sea software) favoreces el trabajo en equipo, revisión, etc

Hablé sobre todo esto en un par de artículos en el blog de Panel Sistemas:

Siguiente

En el próximo post, una vez que tenemos instalado asciidoctor y hemos visto casos de uso, intentaré explicar paso a paso un ejemplo sencillo pero completo

Follow comments at Telegram channel

2019 - 2020 | Mixed with Bootstrap | Baked with JBake v2.6.4