🥇Præsentation som kode, eller Hvorfor jeg ikke længere bruger Powerpoint

Det virker som om, jeg har haft muligheden for at lave Dutzende af præsentationer for kolleger, kunder og offentlige taler i min karriere inden for IT. I mange år har PowerPoint som et værktøj til at lave dias været det naturlige og pålidelige valg for mig. Men i år har situationen ændret sig kvalitativt. Fra februar til maj har jeg haft mulighed for at tale til fem konferencer, og diasene til mine foredrag skulle laves hurtigt, men med høj kvalitet. Spørgsmålet om at delegere den del af arbejdet, der vedrører den visuelle design af diasene, til andre mennesker kom op. En gang forsøgte jeg at arbejde med en designer ved at sende .pptx-filer via e-mail, men arbejdet blev til kaos: ingen vidste, hvilken version af diasene der var 'den nyeste', og layoutet 'skred' på grund af forskelle i versioner af PowerPoint og skrifttyper på vores computere. Så jeg besluttede at prøve noget nyt. Jeg prøvede, og siden da har jeg ikke tænkt på at vende tilbage til PowerPoint.

Hvad vi ønsker

For omkring halvandet år siden besluttede vi i virksomheden at stoppe med at bruge Word til at lave projektal dokumentation, da vi stødte på de samme problemer: selvom Word er godt til at skrive et lille dokument, opstår der vanskeligheder med samarbejde og at få en ensartet kvalitet, når mængden vokser. Vores valg faldt på AsciiDoctor, og vi stopper aldrig med at glæde os over dette valg, men det er et emne for en anden artikel. Omtrent på samme tid indså vi effektiviteten af et af DevOps-principperne 'everything as code', så valget af krav til den nye teknologi til at lave præsentationsdias var ret indlysende:

Præsentationen skal være en plain text-fil i et markup-sprog.
Diasene handler om udviklingsprojekter, så markup'en skal gøre det muligt nemt at indsætte
- kodefragmenter med syntaksfarvning,
- simple diagrammer som geometriske figurer forbundet med pile,
- UML-diagrammer, flowcharts og andet.
Præsentationsprojektet skal opbevares i et versionskontrolsystem.
Validering og opbygning af de færdige dias skal ske i et CI-system.

I dag er der to grundlæggende muligheder for at lave dias på markup-sprog: pakken beamer til LaTeX eller en af rammerne til at lave dias i HTML/CSS (RevealJS, remark, deck.js og mange andre).

Selv om min sjæl hælder mod LaTeX, indikerede fornuften, at valget af en løsning, som ikke kun jeg skulle bruge, måtte være på siden af en løsning, der var kendt af en bredere kreds. Ikke alle kender LaTeX, og hvis din daglige praksis ikke er forbundet med at skrive videnskabelige artikler, er det usandsynligt, at du har tid til at dykke ned i den enorme og komplekse verden af dette system.

Men at have kendskab til HTML/CSS er ikke ligefrem en udbredt færdighed: jeg ejer, for eksempel, det ikke i fuldt omfang. Heldigvis kommer allerede kendte AsciiDoctor os til hjælp: en converter, asciidoctor-revealjs giver os mulighed for at skabe RevealJS-slides ved at bruge AsciiDoctor-markup. Og den er nem at lære og tilgængelig for alle!

Sådan koder man slides

For at forstå essensen af at kode slides i AsciiDoctor, er det nemmest at give konkrete eksempler. Alle de eksempler er fra reelle slides, jeg har lavet til mine konferencer i år.

Slide med en overskrift og en liste, hvor punkterne åbner ét ad gangen:

== Hvorfor har vi brug for Streams API?

[%step]
* Real-time stream processing
* Stream-lignende API (map / reduce)
* Under overfladen:
** Automatisk offset commit
** Rebalancering
** Intern tilstand af behandlere
** Let skalering

Resultat

Overskrift og fragment af kildekoden med syntaksfremhævelse:

== Kafka Streams API: Overordnet struktur af KStreams-applikationen

[source,java]
----
StreamsConfig config = ...;
//Her sætter vi forskellige indstillinger

Topology topology = new StreamsBuilder()
//Her bygger vi topologien
....build();
----

Resultat

Under forberedelsen til præsentationen bliver demonstrationseksemplerne på koden gentagne gange revideret og forbedret, derfor er muligheden for hurtigt at kopiere og indsætte "rå kode" direkte ind i sliden uvurderlig, så demoeksemplet forbliver aktuelt uden at bekymre sig om syntaksfremhævelse.

Overskrift, illustration og tekst (vi laver layoutet på sliden i cellerne AsciDoctor-tabeller):

== Kafka Streams in Action

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

Resultat

Nogle gange er overskriften ikke nødvendig, og for at illustrere din tanke er det bare et billede i fuld skærm, der er brug for:

[%notitle]
== At leve i legacy er ikke let

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

Resultat

Ofte er det nødvendigt at underbygge en tanke med en simpel diagram, i form af "bokse forbundet med pile". Heldigvis er AsciiDoctor integreret med systemet Graphviz — et sprog, der muliggør beskrivelse af grafdiagrammer baseret på beskrivelsen af noder og forbindelser imellem dem. Det er nødvendigt at lære Graphviz, men det er relativt let at gøre det ud fra eksisterende eksempler! Sådan ser det ud:

== Skriver "Bet Totalling App"

Hvad er den samlede udbetaling for de placeringer, hvis udfaldet går hjem?

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

Resultat

I tilfælde af, at det er nødvendigt at redigere etiketten på figuren, ændre retningen af pilen osv. — kan dette gøres direkte i præsentationskoden i stedet for at tegne billedet igen et andet sted og indsætte det på diaset. Dette øger hastigheden på arbejdet med diasene betydeligt.

Et lidt mere komplekst eksempel:

== Ugenkendelig samling
[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;}
}
-----

Resultat

Forresten er det praktisk at eksperimentere med Graphviz og afkode billederne på siden Graphviz online.

Endelig, hvis det er nødvendigt at indsætte et flowdiagram, klasse-diagram eller et andet standardiseret diagram på diaset, kan endnu et system, der er integreret med AsciiDoctor, være til stor hjælp, PlantUML. Om de omfattende muligheder i PlantUML har min kollega Nikolai Potashnikov skrevet et separat indlæg.

At omdanne præsentationsprojektet til kode, der opbevares i versionskontrolsystemet, giver mulighed for at organisere samarbejde om præsentationen, først og fremmest ved at opdele opgaverne om indholdsoprettelse og design. Design af diasene (skrifttyper, baggrunde, margener) i RevealJS beskrives med CSS. Mine personlige færdigheder i CSS formidles bedst af denne gif — men det er ikke skræmmende, når der er folk, der arbejder med CSS meget mere dygtigt og hurtigere end jeg. Resultatet er, at vi i lyset af den hastende deadline for præsentationen kan arbejde samtidig på forskellige filer via Git og øge hastigheden på samarbejdet, hvilket er umuligt ved at sende .pptx-filer via e-mail.

Samling af HTML-side med dias

Rå tekst-kilder er gode, men hvordan kan de kompilere til selve præsentationen?

AsciiDoctor er et projekt skrevet i Ruby, og det kan startes på flere måder. For det første kan du installere Ruby-sproget og køre asciidoctor direkte, hvilket nok er mest nærliggende for Ruby-udviklere.

Hvis du ikke ønsker at rode med installation af Ruby, kan du bruge Docker-billedet asciidoctor/docker-asciidoctor, som ved opstart kan tilslutte en mappe med projektets kilder via VOLUME og få resultatet på det angivne sted.

Den løsning, jeg endte med, kan virke lidt overraskende, men den er mest bekvem for mig som Java-udvikler. Den kræver hverken installation af Ruby eller tilstedeværelse af Docker, men gør det muligt at generere dias ved hjælp af et Maven-script.

Sagen er den, at projektet JRuby — Java-implementeringen af Ruby-sproget — er så godt, at det tillader at køre næsten alt, der er skabt for Ruby, på Java-maskinen, og kørsel af AsciiDoctor er en af de mest almindelige anvendelser af JRuby.

Tilstedeværelsen af asciidoctor-maven-plugin muliggør opsamling af AsciiDoctor-dokumentationen, som er en del af Java-projektet (som vi anvender aktivt). Her downloader Maven automatisk AsciiDoctor og JRuby, og AsciiDoctor udføres i JRuby-miljøet: der er ikke behov for at installere noget på maskinen! (Bortset fra pakken graphviz, som er nødvendig, hvis du vil bruge grafik fra GraphViz eller PlantUML.) Det er tilstrækkeligt at placere dine .adoc-filer i mappen src/main/asciidoc/. Her er et eksempel på monumentet, der samler dias med diagrammer.

Konvertering af dias til PDF

Selv om HTML-versionen af diasene er fuldt ud selvstændig, er det stadig nødvendigt at have en PDF-version af diasene. For det første sker det ofte, at på nogle konferencer, hvor de ikke giver taleren mulighed for at tilslutte sin egen bærbare computer, kræver de dias "strikt i pptx- eller pdf-format", uden at forvente, at de også findes i HTML. For det andet er det god tone at sende arrangørerne en uforanderlig version af dine dias, som de blev vist under præsentationen, i PDF-format til offentliggørelse af filen i konferencens materialer.

Heldigvis klarer Node.js-værktøjet decktape, der er bygget på basesystemet Puppeteer — et automatiseringssystem til at styre Chrome-browseren. For at konvertere en RevealJS-præsentation til PDF kan du bruge kommandoen

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

To tricks ved opstarten af decktape, som jeg måtte finde frem til gennem forsøg og fejl:

tilladelse via parameter -s skal angives med en dobbelt margin, ellers kan der opstå problemer med konverteringsresultaterne
i URL'en til HTML-versionen af præsentationen skal parameteren videregives ?fragments=true, hvilket giver mulighed for at skabe en separat PDF-side for hver mellemtilstand af dit dias (for eksempel fem sider for fem punkter på listen, hvis de vises en efter en). Dette gør det muligt at bruge denne PDF som præsentation under en tale.

Automatisk opbygning og offentliggørelse på internettet

Det er praktisk, når dias automatisk opbygges, når der foretages ændringer i versionskontrolsystemet, og endnu mere praktisk, når de automatisk opbyggede dias offentliggøres på internettet til offentlig brug. Dias fra internettet kan nemt 'afspilles' foran publikum fra hvilken som helst maskine, der er tilsluttet internettet og en projektor.

Da vi bruger GitHub i vores arbejde, er et naturligt valg af CI-system TravisCI, og til hosting af de færdige præsentationer — github.io. Idéen med github.io er, at alt statisk indhold, der er placeret i grenen gh-pages af dit projekt på GitHub, bliver tilgængeligt på adressen .gihub.io/.

Den fulde konfigurationsfil for TravisCI, der omfatter opbygningen af HTML-versionen af siden ved hjælp af Maven, konverteringen til PDF ved hjælp af decktape og uploade resultatet til grenen gh-pages til offentliggørelse på github.io, ser sådan ud så.

For at bygge et sådant projekt på TravisCI-siden skal miljøvariablerne konfigureres

GH_REF — en værdi af typen github.com/inponomarev/csa-hb
GH_TOKEN — adgangstoken til GitHub. Kan fås i GitHub-indstillingerne i din profil, Developer Settings -> Personal Access Tokens. Hvis du uploader præsentationen til et offentligt repository, er det tilstrækkeligt at angive den eneste adgangsniveau 'Access public repositories' for dette token.
GH_USER_EMAIL / GH_USER_NAME — parret navn/email, hvormed der vil blive udført en push til grenen gh-pages.

Således fører hver commit af præsentationskoden på GitHub til automatisk rekonstruktion af dias i HTML- og PDF-formater og gen-upload til github.io. (Selvfølgelig skal du kun uploade de præsentationer til github.io, som du ønsker at gøre offentlige i sidste ende.)

Eksempler på projekter

Til sidst — links til et par eksempler på præsentationsprojekter med konfigurerede Maven-scripts og CI-konfigurationer til Travis-CI, som kan klones og bruges til at oprette egne præsentationsprojekter: