🥇Apresentação como código, ou Por que não uso mais o PowerPoint

Parece que já fiz dezenas de apresentações para colegas, clientes e discursos públicos ao longo da minha carreira em TI. Durante muitos anos, o PowerPoint foi minha escolha natural e confiável para a elaboração de slides. Mas este ano a situação mudou radicalmente. De fevereiro a maio, participei de cinco conferências e os slides para as apresentações precisavam ser preparados em um curto espaço de tempo, mas com qualidade. Surgiu a questão de delegar a parte do trabalho relacionada ao design visual dos slides para outras pessoas. Uma vez, tentei trabalhar com um designer, enviando arquivos .pptx por e-mail, mas o trabalho se transformou em um caos: ninguém sabia qual versão dos slides era a 'mais nova', e a formatação 'deslizou' devido às diferenças nas versões do PowerPoint e nas fontes em nossas máquinas. Então, decidi tentar algo novo. Tentei, e desde então não penso em voltar ao PowerPoint.

O que queremos

Cerca de um ano e meio atrás, nossa empresa desistiu de usar o Word para criar documentação de projetos, enfrentando os mesmos problemas: embora o Word seja bom para digitar um pequeno documento, à medida que o volume aumenta, dificuldades com colaboração e obtenção de um formato de qualidade e unificado começam a surgir. Nossa escolha recaiu sobre AsciiDoctor, e não paramos de nos alegrar com essa decisão, mas esse é um tema para um artigo separado. Foi mais ou menos nessa época que conhecemos a eficácia de um dos princípios DevOps, 'tudo como código', portanto, a escolha dos requisitos para a nova tecnologia de criação de slides de apresentação era bastante óbvia:

A apresentação deve ser um arquivo de texto simples em uma linguagem de marcação.
Os slides são sobre projetos de desenvolvimento, então a marcação deve permitir facilmente, sem recorrer a sistemas externos, inserir
- fragmentos de código com destaque de sintaxe,
- diagramas simples na forma de figuras geométricas conectadas por setas,
- diagramas UML, fluxogramas e outros.
O projeto da apresentação deve ser armazenado em um sistema de controle de versões.
A validação e a geração dos slides prontos devem ser realizadas em um sistema CI.

Atualmente, existem duas opções básicas para criar slides em linguagens de marcação: o pacote beamer para LaTeX ou um dos frameworks para criação de slides em HTML/CSS (RevealJS, remark, deck.js e muitos outros).

Embora minha alma pertença ao LaTeX, a razão sugeria que a escolha de uma solução que não utilizarei sozinho deve estar ao lado de uma solução que é mais conhecida por um público mais amplo. Nem todos conhecem o LaTeX, e se sua prática diária não estiver relacionada à redação de artigos científicos, é improvável que você tenha tempo para se aprofundar no vasto e complexo mundo desse sistema.

No entanto, o domínio de HTML/CSS também não é exatamente uma habilidade amplamente difundida: eu, por exemplo, não o domino completamente. Felizmente, aqui entra em cena o já familiar AsciiDoctor: um conversor asciidoctor-revealjs que permite criar slides RevealJS usando a marcação do AsciiDoctor. E isso é fácil de aprender e acessível a todos!

Como codificar slides

Para entender a essência da codificação de slides no AsciiDoctor, é mais fácil apresentar exemplos concretos. Todos eles vêm de slides reais que preparei para minhas apresentações em conferências este ano.

Um slide com título e lista com itens que aparecem um a um:

== Por que precisamos do Streams API?

[%step]
* Processamento de streams em tempo real
* API semelhante a streams (map/reduce)
* Por trás das câmeras:
** Commit automático de offset
** Rebalanceamento
** Estado interno dos processadores
** Escalonamento fácil

Resultado

Título e um trecho de código-fonte com destaque de sintaxe:

== Kafka Streams API: estrutura geral de um aplicativo KStreams

[source,java]
----
StreamsConfig config = ...;
// Aqui definimos várias opções

Topology topology = new StreamsBuilder()
// Aqui construímos a topologia
....build();
----

Resultado

Durante a preparação para a apresentação, os exemplos de código demonstrativos passam por várias revisões e melhorias, por isso é inestimável a possibilidade de copiar e colar rapidamente o "código bruto" diretamente no slide, garantindo a atualidade do exemplo de demonstração sem se preocupar com o destaque de sintaxe.

Título, ilustração e texto (a disposição no slide é feita em células das tabelas AsciiDoctor):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, Novembro de 2018
* Exemplos de código para Kafka 1.0
|===

Resultado

Às vezes, um título não é necessário, e para ilustrar seu pensamento basta uma imagem em tela cheia:

[%notitle]
== Viver em legados não é fácil

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

Resultado

Frequentemente, é necessário reforçar uma ideia com um simples diagrama, na forma de "caixas conectadas por setas". Felizmente, o AsciiDoctor é integrado ao sistema Graphviz — uma linguagem que permite descrever diagramas de grafos com base na descrição de nós e suas conexões. É preciso aprender Graphviz, mas com os exemplos disponíveis, isso se torna bastante fácil! Veja como isso se parece:

== Escrevendo o "App de Totais de Apostas"

Qual é o valor dos pagamentos pelas apostas feitas, se o resultado ocorrer?

[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="Loja Local"; fixedsize="true"; width="1.5"]
Source -> MapVal -> Sum -> Sink
Sum -> Store [dir=both; label=" n "]
{rank = same; Store; Sum;}
}
-----

Resultado

Caso seja necessário editar a legenda da figura, alterar a direção das setas, etc. — isso pode ser feito diretamente no código da apresentação, em vez de redesenhar a imagem em algum lugar e reinseri-la no slide. Isso aumenta significativamente a velocidade de trabalho nos slides.

Um exemplo mais complicado:

== Compilação Não Reproduzível
[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

A propósito, é conveniente experimentar com Graphviz e depurar imagens na página Graphviz online.

Finalmente, se precisar inserir um fluxograma, diagrama de classes ou outro diagrama padronizado no slide, outro sistema integrado com AsciiDoctor pode ajudar, PlantUML. Meu colega Nikolai Potashnikov escreveu sobre as amplas capacidades do PlantUML em um post separado.

Transformar o projeto de apresentação em código armazenado em um sistema de controle de versões permite organizar o trabalho colaborativo na apresentação, especialmente separando as tarefas de criação de conteúdo e design. A formatação dos slides (fontes, fundos, margens) no RevealJS é descrita com CSS. Minha habilidade pessoal em lidar com CSS é melhor representada nesta GIF — mas isso não é um problema, quando há pessoas que trabalham com CSS muito mais habilidosas e rápidas que eu. No final, resulta que, em condições de um prazo de apresentação que se aproxima rapidamente, podemos trabalhar simultaneamente em diferentes arquivos via Git e aumentar a velocidade do trabalho colaborativo, algo impossível com o envio de arquivos .pptx por e-mail.

Compilação da página HTML com os slides

Plain text-templates são ótimos, mas como compilá-los na própria apresentação?

AsciiDoctor é um projeto escrito em Ruby, e pode ser iniciado de várias maneiras. Primeiro, você pode instalar a linguagem Ruby e rodar o asciidoctor diretamente, o que provavelmente será mais familiar para desenvolvedores Ruby.

Se você não quiser se preocupar com a instalação do Ruby, pode usar a imagem docker asciidoctor/docker-asciidoctor, na qual, ao iniciar, é possível conectar uma pasta com as fontes do projeto através do VOLUME e obter o resultado em um local especificado.

A opção que eu escolhi pode parecer um pouco inesperada, mas é a mais conveniente para mim como desenvolvedor Java. Ela não requer a instalação do Ruby nem a presença do docker, mas permite gerar slides usando um script Maven.

O fato é que o projeto JRuby — a implementação Java da linguagem Ruby — é tão bom que permite rodar na máquina Java praticamente tudo que foi criado para Ruby, e executar o AsciiDoctor é uma das aplicações mais comuns do JRuby.

A presença de asciidoctor-maven-plugin permite construir documentação AsciiDoctor, que faz parte de um projeto Java (o que usamos ativamente). Assim, tanto o AsciiDoctor quanto o JRuby são baixados automaticamente pelo Maven, e o AsciiDoctor é executado no ambiente JRuby: não é necessário instalar nada na máquina! (Exceto o pacote graphviz, que é necessário se você quiser usar gráficos do GraphViz ou PlantUML.) Basta colocar seus arquivos .adoc na pasta src/main/asciidoc/. Aqui está um exemplo de monumento, coletando slides com diagramas.

Conversão de slides em PDF

Embora a versão HTML dos slides seja totalmente independente, ter uma versão em PDF dos slides também é às vezes necessário. Primeiro, acontece que em algumas conferências, que não fornecem ao palestrante a possibilidade de conectar seu próprio laptop, exigem que os slides sejam 'estritamente no formato pptx ou pdf', sem esperar que eles também estejam em HTML. Em segundo lugar, é de bom tom enviar aos organizadores uma versão imutável dos seus slides da forma como foram apresentados, em formato PDF para publicação no material da conferência.

Felizmente, essa tarefa é resolvida pela ferramenta Node.js decktape, baseada em Puppeteer — um sistema de automação para controle do navegador Chrome. Converter uma apresentação RevealJS em PDF pode ser feito pelo comando

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

Duas dicas ao executar o decktape, que chegaram até mim por tentativa e erro:

permissão através do parâmetro -s deve ser definido com um excesso de duas vezes, caso contrário, podem ocorrer problemas com os resultados da conversão
no URL da versão HTML da apresentação, deve-se passar o parâmetro ?fragments=true, o que permitirá criar uma página PDF separada para cada estado intermitente do seu slide (por exemplo, cinco páginas para cinco itens de lista, se eles forem mostrados um após o outro). Isso permitirá usar esse PDF como uma apresentação ao fazer uma exposição.

Compilação e publicação automática na web

É conveniente quando os slides são montados automaticamente ao ocorrerem alterações no sistema de controle de versão, e ainda mais conveniente quando os slides compilados automaticamente são enviados para a internet para uso público. Slides da internet podem ser facilmente 'reproduzidos' diante de uma audiência a partir de qualquer máquina conectada à internet e a um projetor.

Como usamos o GitHub em nosso trabalho, a escolha natural para o sistema CI é TravisCI, e para hospedar as apresentações prontas — github.io. A ideia do github.io é que qualquer conteúdo estático colocado na branch gh-pages do seu projeto no GitHub torna-se acessível pelo endereço .gihub.io/.

O arquivo de configuração completo do TravisCI, incluindo a compilação da versão HTML da página com o auxílio do Maven, conversão para PDF usando decktape e upload dos resultados para a branch gh-pages para publicação em github.io, fica assim.

Para compilar tal projeto do lado do TravisCI, é necessário configurar as variáveis de ambiente

GH_REF — valor do tipo github.com/inponomarev/csa-hb
GH_TOKEN — token de acesso ao GitHub. Pode ser obtido no GitHub nas configurações do seu perfil, Configurações do Desenvolvedor -> Tokens de Acesso Pessoal. Se você estiver publicando a apresentação em um repositório público, para este token, basta indicar um único nível de acesso 'Acessar repositórios públicos'.
GH_USER_EMAIL / GH_USER_NAME — par nome/e-mail, sob o qual o push será realizado na branch gh-pages.

Dessa forma, cada commit do código da apresentação no GitHub leva à reconstrução automática dos slides nos formatos HTML e PDF e ao ressurgimento deles no github.io. (Claro, você deve publicar no github.io apenas as apresentações que deseja tornar públicas no final.)

Exemplos de projetos

Por fim, aqui estão links para alguns exemplos de projetos de apresentações com scripts Maven configurados e configurações de CI para Travis-CI, que podem ser clonados e usados na criação de seus próprios projetos de apresentação: