| | 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.

http://uoc.gitlab.io/2016/AdminRedesSO/AGUILERA_GONZALEZ_JORGE-ARSO/Modulo_6/ArticuloFontsecaBreach.pdf

• Trabajo Fin de Grado

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

https://telotraigodemipueblo.gitlab.io/tfg/pdf/memoria.pdf

• Documentar un proyecto

Documentar un proyecto, explicando funcionalidades, ejemplos, etc,

https://puravida-asciidoctor.gitlab.io/asciidoctor-extensions/

• Página comercial de una empresa

Crear la landing page de una empresa/producto

https://puravida-software.gitlab.io/main/index.html

• 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

https://groovy-lang.gitlab.io/101-scripts/

https://groovy-lang.gitlab.io/101-scripts/101-groovy-scripts-pdf.pdf

https://groovy-lang.gitlab.io/101-scripts/101-groovy-scripts-epub.epub

• Presentación de una charla

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

Slides:

https://www.slideshare.net/JorgeAguilera12/write-gradle-plugins

• Libro digital en Amazon

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

https://www.amazon.es/Tutorial-Asciidoctor-b%C3%A1sica-Jorge-Aguilera-ebook/dp/B07518QBR4

(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:

https://www.panel.es/blog/aproximacion-documentacion-continua-parte-i/https://www.panel.es/blog/aproximacion-documentacion-continua-parte-ii/

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