🥇Presentatie als code, of Waarom ik geen PowerPoint meer gebruik

Het lijkt erop dat ik tientallen presentaties heb moeten maken voor collega's, klanten en publieke optredens gedurende mijn carrière in de IT. Jarenlang was PowerPoint voor mij de natuurlijke en betrouwbare keuze voor het maken van dia's. Maar dit jaar is de situatie wezenlijk veranderd. Van februari tot mei heb ik gesproken op vijf conferenties, en de dia's voor de lezingen moesten snel, maar kwalitatief worden voorbereid. De vraag rees hoe ik het visuele ontwerp van de dia's aan anderen kon delegeren. Op een keer probeerde ik samen te werken met een ontwerper door .pptx-bestanden per e-mail te sturen, maar het werk werd een chaos: niemand wist welke versie van de dia's de 'nieuwste' was en de opmaak 'verknalde' door verschillen in PowerPoint-versies en lettertypen op onze machines. Dus besloot ik iets nieuws te proberen. Ik heb het geprobeerd, en sindsdien denk ik er niet meer aan om terug te gaan naar PowerPoint.

Wat we willen

Bijna anderhalf jaar geleden hebben we bij het bedrijf besloten om Word niet meer te gebruiken voor het opstellen van projectdocumentatie, omdat we tegen dezelfde problemen aanliepen: hoewel Word goed is om een klein document in te typen, ontstaan er bij groeiende volumes moeilijkheden met samenwerken en het verkrijgen van kwalitatieve en uniforme opmaak. We kozen voor AsciiDoctor, en we zijn nog steeds blij met die keuze, maar dat is een onderwerp voor een apart artikel. Rond dezelfde tijd ontdekten we de effectiviteit van een van de DevOps-principes 'everything as code', waardoor de keuze voor de nieuwe technologie voor het maken van presentatie-dia's nogal vanzelfsprekend was:

De presentatie moet een platte tekstbestand zijn in opmaaktalen.
Onze dia's zijn over ontwikkelingsprojecten, dus de opmaak moet eenvoudig het invoegen van
- codefragmenten met syntaxisaccentuering mogelijk maken,
- eenvoudige diagrammen in de vorm van geometrische figuren verbonden met pijlen,
- UML-diagrammen, stroomdiagrammen, en meer.
Het project van de presentatie moet in een versiebeheersysteem worden opgeslagen.
Validatie en assemblage van de voltooide dia's moeten in een CI-systeem plaatsvinden.

Vandaag de dag zijn er twee basisopties voor het maken van dia's in opmaaktalen: het pakket beamer voor LaTeX of een van de frameworks voor het maken van dia's in HTML/CSS (RevealJS, remark, deck.js en vele anderen).

Hoewel mijn hart naar LaTeX uitgaat, suggereerde mijn verstand dat de keuze voor een oplossing die niet alleen door mij gebruikt zal worden, moet vallen op iets dat bekender is bij een breder publiek. Niet iedereen kent LaTeX, en als je dagelijkse praktijk niet bestaat uit het schrijven van wetenschappelijke artikelen, zal je waarschijnlijk niet de tijd hebben om je te verdiepen in de enorme en complexe wereld van dit systeem.

Toch is het beheersen van HTML/CSS ook geen alomtegenwoordig vaardigheid: ik zelf beheers het bijvoorbeeld niet volledig. Gelukkig komt de al bekende AsciiDoctor hier te hulp: de converter. asciidoctor-revealjs maakt het mogelijk om RevealJS-slides te creëren met AsciiDoctor-markup. En die markup is eenvoudig te leren en voor iedereen toegankelijk!

Hoe slides te coderen

Om de essentie van het coderen van slides in AsciiDoctor te begrijpen, is het het gemakkelijkst om concrete voorbeelden te geven. Ze zijn allemaal afkomstig uit echte slides die ik dit jaar heb gemaakt voor mijn conferentiepresentaties.

Een slide met een titel en een lijst met de punten die één voor één verschijnen:

== Waarom hebben we Streams API nodig?

[%step]
* Real-time streamverwerking
* Stream-achtige API (map / reduce)
* Onder de motorkap:
** Automatische offset validatie
** Herbalancering
** Interne toestand van de verwerkers
** Gemakkelijk schalen

Resultaat

Een titel en een fragment van broncode met syntaxisaccentuering:

== Kafka Streams API: algemene structuur van een KStreams-toepassing

[source,java]
----
StreamsConfig config = ...;
// Hier stellen we verschillende opties in

Topology topology = new StreamsBuilder()
// Hier bouwen we de topologie
....build();
----

Resultaat

In de voorbereidende fase voor de presentatie worden de demonstratiecodevoorbeelden meerdere keren herzien en verbeterd, dus is de mogelijkheid om snel de 'ruwe code' rechtstreeks in de slide te kopiëren en plakken van onschatbare waarde. Dit zorgt voor de actualiteit van het demo voorbeeld en maakt je geen zorgen over syntaxisaccentuering.

Titel, illustratie en tekst (de lay-out op de slide maken we in de cellen tabellen van AsciiDoctor):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, november 2018
* Voorbeelden van code voor Kafka 1.0
|===

Resultaat

Soms is een titel niet nodig, maar heb je gewoon een afbeelding over het volle scherm nodig ter illustratie van je gedachte:

[%notitle]
== Leven in legacy is moeilijk

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

Resultaat

Vaak moet een gedachte worden ondersteund door een simpele diagram, in de vorm van 'vierkanten verbonden met pijlen'. Gelukkig is AsciiDoctor geïntegreerd met het systeem Graphviz — een taal die het mogelijk maakt om grafische diagrammen te beschrijven op basis van de beschrijving van knooppunten en verbindingen daartussen. Het leren van Graphviz kost tijd, maar aan de hand van de bestaande voorbeelden is dat vrij eenvoudig! Dit is hoe het eruitziet:

== We schrijven “Bet Totalling App”

Wat is het totaalbedrag aan uitbetalingen voor de geplaatste weddenschappen, als de uitkomst gunstig is?

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

Resultaat

Als het nodig is om het label op een figuur te bewerken, de richting van de pijl te veranderen, enzovoort, kan dit rechtstreeks in de presentatiecode worden gedaan, in plaats van ergens een afbeelding opnieuw te moeten tekenen en deze opnieuw in de dia in te voegen. Dit verhoogt aanzienlijk de snelheid van het werken aan dia's.

Een iets complexer voorbeeld:

== Niet-reproduceerbare bouw
[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;}
}
-----

Resultaat

Overigens is het handig om met Graphviz te experimenteren en afbeeldingen te debuggen op de pagina Graphviz online.

Ten slotte, als je een blokdiagram, een klassen diagram of een ander gestandaardiseerd diagram in een dia moet invoegen, dan kan een ander geïntegreerd systeem, dat samenwerkt met AsciiDoctor, van pas komen, PlantUML. Mijn collega Nikolai Potashnikov heeft een apart bericht geschreven.

De transformatie van een presentatiewerk naar code, die wordt opgeslagen in een versiebeheersysteem, maakt het mogelijk om samen te werken aan de presentatie, vooral door de taken voor het maken van inhoud en opmaak te scheiden. De opmaak van dia's (lettertypen, achtergronden, inspringingen) in RevealJS wordt beschreven met behulp van CSS. Mijn persoonlijke vaardigheid om met CSS om te gaan, wordt het beste weergegeven door deze gif — maar dat is niet erg, wanneer er mensen zijn die beter en sneller met CSS werken dan ik. Uiteindelijk betekent dit dat we, in de aanloop naar de snel naderende deadline voor de presentatie, tegelijkertijd aan verschillende bestanden kunnen werken via Git en de snelheid van samenwerking kunnen vergroten, wat onmogelijk zou zijn bij het verzenden van .pptx-bestanden per e-mail.

Bouw van een HTML-pagina met dia's

Platte tekstbronnen zijn geweldig, maar hoe compileer je ze in de presentatie zelf?

AsciiDoctor is een project dat in Ruby is geschreven, en je kunt het op verschillende manieren uitvoeren. Ten eerste kun je de Ruby-taal installeren en Asciidoctor direct starten, wat waarschijnlijk het dichtst bij Ruby-ontwikkelaars ligt.

Als je geen zin hebt in het installeren van Ruby, kun je gebruikmaken van een Docker-image. asciidoctor/docker-asciidoctor, waarin je bij het starten de map met projectbronnen via VOLUME kunt koppelen en op de opgegeven plaats het resultaat kunt krijgen.

De optie waar ik op ben gestuit, lijkt misschien een beetje onverwacht, maar is het meest handig voor mij als Java-ontwikkelaar. Het vereist noch de installatie van Ruby, noch de aanwezigheid van Docker, maar stelt je in staat om dia's te genereren met behulp van een Maven-script.

Het is namelijk zo dat het project JRuby — een Java-implementatie van de Ruby-taal — zo goed is dat het mogelijk maakt om praktisch alles wat voor Ruby is gemaakt in de Java Virtual Machine uit te voeren, en het uitvoeren van AsciiDoctor is een van de meest voorkomende toepassingen van JRuby.

Aanwezigheid asciidoctor-maven-plugin maakt het mogelijk om AsciiDoctor-documentatie te bouwen die deel uitmaakt van een Java-project (waar we actief gebruik van maken). Hierbij worden AsciiDoctor en JRuby automatisch door Maven gedownload en wordt AsciiDoctor uitgevoerd in de JRuby-omgeving: je hoeft niets op je machine te installeren! (Behalve het pakket graphviz, dat nodig is als je grafieken met GraphViz of PlantUML wilt gebruiken.) Het is voldoende om je .adoc-bestanden in de map src/main/asciidoc/. Hier is voorbeeld van een monument, dat dia's met diagrammen genereert.

Conversie van dia's naar PDF

Hoewel de HTML-versie van de dia's volkomen op zichzelf staat, is het toch soms nodig om ook een PDF-versie van de dia's te hebben. Ten eerste kan het zijn dat op sommige conferenties, die de spreker niet de mogelijkheid bieden om zijn eigen laptop aan te sluiten, dia's "strict in pptx- of pdf-formaat" eisen, zonder te verwachten dat ze ook in HTML beschikbaar zijn. Ten tweede is het goed gebruik om de organisatoren een onveranderlijke versie van je dia's te sturen in de vorm waarin ze tijdens de presentatie zijn getoond, in PDF-indeling voor publicatie in het conferentiemateriaal.

Gelukkig kan de Node.js-tool decktape, gebouwd op basis van Puppeteer — een automatiseringssysteem voor het besturen van de Chrome-browser. Om een RevealJS-presentatie naar PDF te converteren, kan je de volgende opdracht gebruiken:

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

Twee trucjes bij het uitvoeren van decktape, die ik door middel van proberen en falen heb ontdekt:

resolutie via parameter -s je moet een dubbele marge instellen, anders kunnen er problemen optreden met de conversieresultaten
in de URL van de HTML-versie van de presentatie moet een parameter worden doorgegeven ?fragments=true, wat het mogelijk maakt om een aparte PDF-pagina te creëren voor elke tussenliggende toestand van je dia (bijvoorbeeld vijf pagina's voor vijf punten in een lijst, als ze één voor één worden weergegeven). Dit maakt het mogelijk om die PDF in zijn geheel als presentatie te gebruiken tijdens een lezing.

Automatische assemblage en publicatie op het web

Het is handig wanneer dia's automatisch worden verzameld bij wijzigingen in het versiebeheersysteem, en nog handiger wanneer automatisch samengestelde dia's op internet worden geplaatst voor algemeen gebruik. Dia's van internet kunnen eenvoudig 'afgespeeld' worden voor een publiek vanaf elke computer die is aangesloten op het internet en een projector.

Aangezien we GitHub gebruiken in ons werk, is de natuurlijke keuze voor een CI-systeem TravisCI, en voor het hosten van kant-en-klare presentaties — github.io. Het idee van github.io is dat elke statische inhoud die in de tak gh-pages van je project op GitHub wordt geplaatst, beschikbaar wordt op het adres .gihub.io/.

Het volledige configuratiebestand van TravisCI, inclusief de compilatie van de HTML-versie van de pagina met Maven, conversie naar PDF met behulp van decktape en het uploaden van de resultaten naar de tak gh-pages voor publicatie op github.io, ziet eruit als zo.

Voor het opbouwen van zo'n project aan de kant van TravisCI moeten omgevingsvariabelen worden ingesteld

GH_REF — een waarde van het type github.com/inponomarev/csa-hb
GH_TOKEN — toegangstoken voor GitHub. Dit kan in GitHub worden verkregen via de instellingen van je profiel, Developer Settings -> Personal Access Tokens. Als je de presentatie in een openbaar repository plaatst, is het genoeg om voor dit token alleen de toegangsrechten voor "Access public repositories" op te geven.
GH_USER_EMAIL / GH_USER_NAME — een paar naam/e-mail waarmee de push naar de tak zal worden uitgevoerd gh-pages.

Zo leidt elke codecommit van de presentatie op GitHub tot een automatische reconstructie van dia's in HTML- en PDF-formaten en het opnieuw uploaden daarvan naar github.io. (Natuurlijk kun je alleen die presentaties op github.io plaatsen die je uiteindelijk openbaar wilt maken.)

Voorbeelden van projecten

Tot slot — links naar een paar voorbeelden van presentatieprojecten met ingestelde Maven-scripts en CI-configuratie voor Travis-CI, die gekloond en gebruikt kunnen worden bij het maken van je eigen presentatieprojecten: