| | 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
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
Top comments (0)