🥇Presentación como código, o por qué ya no uso PowerPoint

Parece que he hecho decenas de presentaciones para colegas, clientes y discursos públicos a lo largo de mi carrera en TI. Durante muchos años, PowerPoint como herramienta para crear diapositivas fue una elección natural y confiable para mí. Pero este año la situación cambió drásticamente. De febrero a mayo, tuve la oportunidad de hablar en cinco conferencias, y necesitaba preparar las diapositivas de las presentaciones en tiempos reducidos, pero con calidad. Surgió la cuestión de delegar esa parte del trabajo relacionada con el diseño visual de las diapositivas a otras personas. Una vez intenté trabajar con un diseñador, enviando archivos .pptx por correo, pero el trabajo se convirtió en un caos: nadie sabía qué versión de las diapositivas era la

Qué queremos

Hace aproximadamente un año y medio, en la empresa decidimos dejar de usar Word para la creación de documentación de proyectos, enfrentándonos a los mismos problemas: aunque Word es bueno para redactar un documento pequeño, a medida que el volumen crece, surgen dificultades con el trabajo colaborativo y la obtención de un formato de calidad y unificado. Nuestra elección fue AsciiDoctor, y no dejamos de alegrarnos por ello, pero ese es un tema para otro artículo. Aproximadamente al mismo tiempo, comprendimos la eficacia de uno de los principios de DevOps 'everything as code', por lo que la elección de requisitos para una nueva tecnología de creación de diapositivas de presentación fue bastante obvia:

La presentación debe consistir en un archivo de texto plano en un lenguaje de marcado.
Las diapositivas tratan sobre proyectos de desarrollo, por lo que el marcado debe permitir insertar fácilmente, sin la ayuda de sistemas externos,
- fragmentos de código con resaltado de sintaxis,
- diagramas simples en forma de figuras geométricas conectadas por flechas,
- diagramas UML, diagramas de flujo y otros.
El proyecto de la presentación debe almacenarse en un sistema de control de versiones.
La validación y la compilación de las diapositivas terminadas deben llevarse a cabo en el sistema CI.

Hoy en día, hay dos opciones básicas para crear diapositivas en lenguajes de marcado: el paquete beamer para LaTeX o uno de los frameworks para crear diapositivas en HTML/CSS (RevealJS,, remark, deck.js y muchos otros).

Aunque mi alma se incline hacia LaTeX, la razón me decía que la elección de una solución que no usaré solo yo debe inclinarse hacia una opción conocida por un público más amplio. No todos conocen LaTeX, y si tu práctica diaria no está relacionada con la redacción de artículos científicos, es poco probable que tengas tiempo para sumergirte en el enorme y complicado mundo de este sistema.

Sin embargo, el dominio de HTML/CSS no es un skill que todos posean: yo, por ejemplo, no lo manejo completamente. Afortunadamente, aquí llega a ayudar AsciiDoctor, que ya conocemos: el conversor asciidoctor-revealjs permite crear presentaciones RevealJS utilizando la sintaxis de AsciiDoctor. ¡Y esa es fácil de aprender y accesible para todos!

Cómo codificar presentaciones

Para entender la esencia de la codificación de presentaciones en AsciiDoctor, es más sencillo proporcionar ejemplos concretos. Todos son de presentaciones reales que hice para mis charlas en conferencias este año.

Una diapositiva con un título y una lista que se abre ítem por ítem:

== ¿Por qué necesitamos Streams API?

[%step]
* Procesamiento de flujos en tiempo real
* API tipo stream (map / reduce)
* Bajo el capó:
** Compromiso automático del offset
** Rebalanceo
** Estado interno de los procesadores
** Escalabilidad sencilla

Resultado

Título y fragmento de código fuente con resaltado de sintaxis:

== Kafka Streams API: estructura general de una aplicación KStreams

[source,java]
----
StreamsConfig config = ...;
// Aquí establecemos varias opciones

Topology topology = new StreamsBuilder()
// Aquí construimos la topología
....build();
----

Resultado

En el proceso de preparación para la charla, los ejemplos de código de demostración son sometidos a múltiples revisiones y mejoras, por lo que es invaluable la posibilidad de copiar y pegar rápidamente el "código bruto" directamente en la diapositiva, asegurando la actualidad del ejemplo de demostración y sin preocuparse sobre el resaltado de sintaxis.

Título, ilustración y texto (distribuimos en celdas de la tabla AsciiDoctor):

== Kafka Streams en Acción

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams en Acción”, noviembre de 2018
* Ejemplos de código para Kafka 1.0
|===

Resultado

A veces no se necesita un título, y para ilustrar tu idea solo se requiere una imagen a pantalla completa:

[%notitle]
== Vivir en legado no es fácil

image::swampman.jpg[canvas, size=cover]

Resultado

A menudo, es necesario respaldar la idea con un simple diagrama, en forma de "cuadrados conectados por flechas". Afortunadamente, AsciiDoctor está integrado con el sistema Graphviz — un lenguaje que permite describir diagramas de grafos basándose en la descripción de los nodos y las conexiones entre ellos. Es necesario aprender Graphviz, pero basado en los ejemplos existentes, ¡es bastante fácil hacerlo! Así es como se ve:

== Escribiendo “Bet Totalling App”

¿Cuál es la suma de los pagos por las apuestas realizadas si ocurre un resultado?

[graphviz, "counting-topology.png"]
-----
digraph G {
graph [ dpi = 150 ];
rankdir="LR";
node [fontsize=18; shape="circle"; fixedsize="true"; width="1.1"];
Store [shape="cylinder"; label="Local Store"; fixedsize="true"; width="1.5"]
Source -> MapVal -> Sum -> Sink
Sum -> Store [dir=both; label=" n "]
{rank = same; Store; Sum;}
}
-----

Resultado

En caso de que sea necesario editar la etiqueta de una figura, cambiar la dirección de la flecha, etc., esto se puede hacer directamente en el código de la presentación, en lugar de tener que redibujar la imagen en otro lugar y volver a insertarla en la diapositiva. Esto aumenta significativamente la velocidad del trabajo en las diapositivas.

Un ejemplo más complejo:

== Construcción no reproducible
[graphviz, "unstable-update.png"]
-----
digraph G {
  rankdir="LR";
  graph [ dpi = 150 ];
  u -> r0;
  u[shape=plaintext; label="linter updaten+ 13 warnings"]
  r0[shape=point, width = 0]
  r1 -> r0[ arrowhead = none, label="master branch" ];
  r0-> r2 [];   b1 -> b4;  r1->b1
  r1[label="150nwarnings"]
  b1[label="± 0nwarnings"]
  b4[label="± 0nwarnings"]
  b4->r2
  r2[label="163nwarnings", color="red", xlabel=<merge blocked>]
  {rank = same; u; r0; b4;}
}
-----

Resultado

Por cierto, es conveniente experimentar con Graphviz y depurar imágenes en la página Graphviz online.

Finalmente, si es necesario insertar un diagrama de bloques, un diagrama de clases u otro diagrama estandarizado en la diapositiva, puede ayudar otro sistema integrado con AsciiDoctor, PlantUML. Sobre las amplias capacidades de PlantUML, mi colega Nikolai Potashnikov escribió un post separado.

Transformar el proyecto de la presentación en código, almacenado en un sistema de control de versiones, permite organizar el trabajo colaborativo en la presentación, principalmente separar las tareas de creación de contenido y diseño. El diseño de las diapositivas (fuentes, fondos, márgenes) en RevealJS se describe mediante CSS. Mi habilidad personal para manejar CSS se transmite mejor a través de este gif — pero no es un problema cuando hay personas trabajando con CSS mucho más hábiles y rápidas que yo. Al final, en condiciones de un plazo de presentación que se acerca rápidamente, podemos trabajar simultáneamente en diferentes archivos a través de Git y mejorar la velocidad del trabajo colaborativo, algo que sería imposible al enviar archivos .pptx por correo electrónico.

Construcción de una página HTML con diapositivas

El texto plano - los fuentes son geniales, pero ¿cómo compilarlo en la propia presentación?

AsciiDoctor es un proyecto escrito en Ruby, y se puede ejecutar de varias maneras. En primer lugar, puedes instalar el lenguaje Ruby y ejecutar asciidoctor directamente, lo que, probablemente, será lo más cercano a los desarrolladores de Ruby.

Si no quieres complicarte con la instalación de Ruby, puedes utilizar la imagen de docker asciidoctor/docker-asciidoctor, que al ejecutarse te permite conectar a través de VOLUME una carpeta con los fuentes del proyecto y obtener el resultado en un lugar determinado.

La opción en la que me detuve puede parecer un poco inesperada, pero es la más conveniente para mí como desarrollador de Java. No requiere ni la instalación de Ruby ni tener docker, pero permite generar diapositivas utilizando un script de Maven.

El hecho es que el proyecto JRuby — la implementación en Java del lenguaje Ruby — es tan bueno que permite ejecutar en la máquina Java prácticamente todo lo creado para Ruby, y ejecutar AsciiDoctor es una de las aplicaciones más comunes de JRuby.

La existencia asciidoctor-maven-plugin permite compilar documentación de AsciiDoctor que forma parte de un proyecto de Java (lo que utilizamos activamente). Al mismo tiempo, AsciiDoctor y JRuby son descargados automáticamente por Maven, y AsciiDoctor se ejecuta en el entorno de JRuby: ¡no necesitas instalar nada en la máquina! (A excepción del paquete graphviz, que es necesario si deseas usar gráficos de GraphViz o PlantUML.) Solo necesitas colocar tus archivos .adoc en la carpeta src/main/asciidoc/. Aquí es un ejemplo de una presentación, que genera diapositivas con diagramas.

Conversión de diapositivas a PDF

Aunque la versión HTML de las diapositivas es completamente autónoma, aún así es necesario tener una versión PDF de las diapositivas. En primer lugar, ocurre que en algunas conferencias, que no permiten al ponente conectar su propio portátil, exigen diapositivas 'estrictamente en formato pptx o pdf', sin esperar que también hay en HTML. En segundo lugar, es una buena práctica enviar a los organizadores una versión inalterable de tus diapositivas tal como fueron mostradas en la presentación, en formato PDF para la publicación del archivo en el material de la conferencia.

Afortunadamente, esta tarea la cumple la utilidad de Node.js decktape, construida sobre Puppeteer — un sistema de automatización del control del navegador Chrome. Puedes convertir una presentación de RevealJS a PDF con el comando

node decktape.js -s 3200x1800 --slides 1-500 
  reveal "file:///index.html?fragments=true" slides.pdf

Dos trucos al ejecutar decktape, a los que llegué mediante prueba y error:

resolución a través de un parámetro -s se debe establecer con un margen del doble, de lo contrario pueden aparecer problemas con los resultados de la conversión
en la URL de la versión HTML de la presentación se debe pasar el parámetro ?fragments=true, lo que permitirá crear una página PDF separada para cada estado intermedio de su diapositiva (por ejemplo, cinco páginas para cinco puntos de la lista, si se muestran uno tras otro). Esto permitirá usar este PDF como presentación durante la exposición.

Compilación y publicación automáticas en la web

Es conveniente cuando las diapositivas se compilan automáticamente al haber cambios en el sistema de control de versiones, y aún más conveniente cuando las diapositivas compiladas automáticamente se publican en internet para uso general. Las diapositivas desde internet se pueden 'reproducir' fácilmente ante la audiencia desde cualquier máquina conectada a internet y a un proyector.

Dado que utilizamos GitHub en nuestro trabajo, la elección natural del sistema CI es TravisCI, y para el hospedaje de presentaciones terminadas — github.io. La idea de github.io es que cualquier contenido estático colocado en la rama gh-pages de su proyecto en GitHub, se vuelve accesible en la dirección .gihub.io/.

El archivo de configuración completo de TravisCI, que incluye la compilación de la versión HTML de la página utilizando Maven, la conversión a PDF con decktape y la carga de resultados en la rama gh-pages para la publicación en github.io, se ve así.

Para compilar un proyecto así en el lado de TravisCI, es necesario configurar las variables de entorno

GH_REF — valor del tipo github.com/inponomarev/csa-hb
GH_TOKEN — token de acceso a GitHub. Puede obtenerlo en GitHub en la configuración de su perfil, Developer Settings -> Personal Access Tokens. Si está publicando la presentación en un repositorio público, para este token es suficiente indicar un solo nivel de acceso "Access public repositories".
GH_USER_EMAIL / GH_USER_NAME — par nombre/correo, bajo el cual se realizará el push en la rama gh-pages.

De esta manera, cada commit de código de la presentación en GitHub provoca la reconstrucción automática de las diapositivas en formatos HTML y PDF y su recarga en github.io. (Por supuesto, solo debe subir a github.io aquellas presentaciones que desea hacer públicas en última instancia.)

Ejemplos de proyectos

Por último, enlaces a un par de ejemplos de proyectos de presentaciones con scripts de Maven configurados y la configuración de CI para Travis-CI, que se pueden clonar y utilizar al crear sus propios proyectos de presentaciones: