🥇Presentation som kod, eller Varför jag inte längre använder Powerpoint

Det verkar som om jag har haft möjlighet att göra tiotals presentationer för kollegor, kunder och offentliga tal under min karriär inom IT. Många år har PowerPoint varit mitt naturliga och pålitliga val för att skapa bildspel. Men i år har situationen förändrats kvalitativt. Från februari till maj hade jag nöjet att tala på fem konferenser, och jag var tvungen att förbereda bilder till föredragen under tidspress, men av god kvalitet. Frågan om att delegera den del av arbetet som rör den visuella designen av bilderna till andra personer uppstod. En gång försökte jag samarbeta med en designer genom att skicka .pptx-filer via e-post, men arbetet förvandlades till kaos: ingen visste vilken version av bilderna som var

Vad vi vill

För ungefär ett och ett halvt år sedan avstod vi i företaget från att använda Word för att skapa projektdokumentation, efter att ha stött på samma problem: även om Word är bra för att skriva en liten dokument, uppstår det svårigheter med samarbete och att få en kvalitativ och enhetlig presentation när volymerna ökar. Vårt val föll på AsciiDoctor, och vi slutar aldrig att glädjas över detta val, men det är ämnet för en annan artikel. Ungefär vid samma tidpunkt upptäckte vi effektiviteten av en av DevOps-principerna "everything as code", så valet av krav för den nya teknologin för att skapa presentationsbilder var ganska uppenbart:

Presentationer bör bestå av en plain text-fil i ett markup-språk.
Bilderna handlar om utvecklingsprojekt, så markupen bör tillåta oss att enkelt, utan att behöva hjälp av externa system, infoga
- kodsnuttar med syntaxmarkering,
- enkla diagram i form av geometriska figurer kopplade med pilar,
- UML-diagram, flödesscheman och liknande.
Projektpresentationen bör lagras i ett versionskontrollsystem.
Validering och byggande av de färdiga bilderna bör göras i en CI-system.

I dag finns det två grundläggande alternativ för att skapa bilder i markup-språk: paketet beamer för LaTeX eller en av ramverken för att skapa bilder i HTML/CSS (RevealJS, remark, deck.js och många andra).

Även om min själ dras till LaTeX, sa mitt förnuft att valet av en lösning som jag inte själva skulle använda, borde vara åt det håll av en lösning som är bekant för en bredare krets. LaTeX är inte välkänt för alla, och om din vardagliga praktik inte handlar om att skriva vetenskapliga artiklar, finns det nog inte tid för att dyka ner i den omfattande, intrikata världen av detta system.

Trots detta är behärskning av HTML/CSS inte ett allmänt förekommande färdighet: jag, till exempel, behärskar det inte helt. Lyckligtvis kommer den redan bekanta AsciiDoctor till hjälp: en konverterare asciidoctor-revealjs som möjliggör skapandet av RevealJS-slides med hjälp av AsciiDoctor-markup. Och den är faktiskt enkel att lära sig och tillgänglig för alla!

Hur man kodar slides

För att förstå kärnan i kodning av slides i AsciiDoctor är det enklast att ge konkreta exempel. Alla dessa kommer från verkliga slides som jag har skapat för mina konferenspresentationer detta år.

En slide med en rubrik och en lista där punkterna dyker upp en efter en:

== Varför behöver vi Streams API?

[%step]
* Realtidsströmbehandling
* Stream-liknande API (map / reduce)
* Under huven:
** Automatisk offset commit
** Rebalansering
** Intern status för behandlare
** Lätt skalning

Resultat

Rubrik och fragment av källkod med syntaxmarkering:

== Kafka Streams API: generell struktur för KStreams-applikationen

[source,java]
----
StreamsConfig config = ...;
// Här ställer vi in olika alternativ

Topology topology = new StreamsBuilder()
// Här bygger vi topologi
....build();
----

Resultat

Under förberedelserna för presentationen genomgår demonstrationskoden upprepade omarbetningar och förbättringar, därför är det ovärderligt att snabbt kunna kopiera och klistra in "rå kod" direkt i sliden, vilket säkerställer relevansen av demonstrationsexemplet utan att behöva bekymra sig om syntaxmarkeringen.

Rubrik, illustration och text (layouten på sliden gör vi i celler tabellen AsciiDoctor):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafkastreams i aktion”, november 2018
* Exempelcode för Kafka 1.0
|===

Resultat

Ibland behövs ingen rubrik, och för att illustrera din tanke behövs bara en bild i fullskärmsläge:

[%notitle]
== Att leva med legacy är inte enkelt

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

Resultat

Ofta behöver en tanke förstärkas med en enkel diagram, i form av "rutor som är kopplade med pilar". Lyckligtvis är AsciiDoctor integrerat med systemet Graphviz — ett språk som möjliggör beskrivning av grafdiagram baserat på beskrivningen av noder och relationer mellan dem. Att bemästra Graphviz kräver tid, men att göra det utifrån befintliga exempel är ganska enkelt! Så här ser det ut:

== Skriver "Bet Totalling App"

Vad är summan av utbetalningarna för gjorda insatser om resultatet slår in?

[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

Om det är nödvändigt att redigera etiketten på figuren, ändra pilens riktning osv. — kan detta göras direkt i presentationskoden, istället för att rita om bilden någon annanstans och sätta in den igen i sliden. Detta ökar avsevärt hastigheten på arbetet med slids.

Ett något mer komplicerat exempel:

== Icke-reproducerbar byggnad
[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

Förresten är det praktiskt att experimentera med Graphviz och justera bilder på sidan Graphviz online.

Slutligen, om det behövs att infoga ett flödesschema, klassdiagram eller någon annan standardiserad diagram, så kan en annan integrerad med AsciiDoctor-systemet komma till hjälp, PlantUML. Om PlantUML:s omfattande möjligheter har min kollega Nikolay Potashnikov skrivit separat post.

Att omvandla presentationsprojektet till kod som lagras i versionskontrollsystemet möjliggör samarbete kring presentationen, framför allt att dela upp ansvaret för innehållsskapande och design. Utformningen av slids (typsnitt, bakgrunder, indrag) i RevealJS beskrivs med hjälp av CSS. Min personliga förmåga att hantera CSS överträffas bäst av denna gif — men det är inget problem när det finns folk som arbetar med CSS snabbare och smidigare än jag. I slutändan innebär det att vi i ljuset av den snabbt närmande deadline för presentationen kan arbeta samtidigt på olika filer via Git och öka hastigheten på det gemensamma arbetet, vilket inte är möjligt vid överföring av .pptx-filer via mejl.

Byggande av HTML-sida med slides

Vanlig textkällor är bra, men hur kompletterar man dem till själva presentationen?

AsciiDoctor är ett projekt skrivet i Ruby och kan köras på flera sätt. För det första kan du installera Ruby-språket och köra asciidoctor direkt, vilket förmodligen kommer att vara mest bekvämt för Ruby-utvecklare.

Om du inte vill ge dig in på att installera Ruby kan du använda Docker-avbildningen asciidoctor/docker-asciidoctor, som vid körning kan koppla en mapp med projektets källor via VOLUME och få resultatet på den angivna platsen.

Alternativet som jag valde kan verka något oväntat, men det är mest bekvämt för mig som Java-utvecklare. Det kräver varken installation av Ruby eller Docker, men tillåter att generera presentationer med hjälp av Maven-skript.

Det är så att projektet JRuby — Java-implementationen av Ruby — är så bra att det tillåter att köra praktiskt taget allt som skapats för Ruby i Java-maskinen, och att köra AsciiDoctor är en av de vanligaste användningarna av JRuby.

Närvaron av asciidoctor-maven-plugin möjliggör att kompilera AsciiDoctor-dokumentation som är en del av ett Java-projekt (vilket vi använder aktivt). Både AsciiDoctor och JRuby laddas ner automatiskt av Maven, och AsciiDoctor körs i JRuby-miljön: ingen installation på maskinen behövs! (Förutom paketet graphviz, som behövs om du vill använda grafik från GraphViz eller PlantUML.) Det räcker med att placera dina .adoc-filer i mappen src/main/asciidoc/. Här är exempel på monument, som samlar presentationer med diagram.

Konvertering av presentationer till PDF

Även om HTML-versionen av presentationerna är fullt självförsörjande, är det fortfarande nödvändigt att ha en PDF-version av presentationerna. För det första kan det hända att vissa konferenser, som inte ger talarna möjlighet att ansluta sina egna bärbara datorer, kräver presentationerna "strikt i pptx- eller pdf-format", utan att förvänta sig att de även finns i HTML. För det andra är det god ton att skicka en oförändrad version av dina presentationer till arrangörerna i det format de visades i, i PDF-format för publicering av filen i konferensmaterialet.

Lyckligtvis hanterar detta uppgift Node.js-verktyget decktape, som bygger på Puppeteer — ett automatiseringssystem för att kontrollera Chrome-webbläsaren. Du kan konvertera en RevealJS-presentation till PDF med kommandot

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

Två knep vid körning av decktape som jag kom fram till genom trial and error:

upplösningen via parameter -s det måste anges med dubbla marginaler, annars kan det uppstå problem med konverteringsresultaten
i URL:en för HTML-versionen av presentationen måste parametrar överföras ?fragments=true, vilket möjliggör skapandet av en separat PDF-sida för varje mellanliggande tillstånd av din bild (till exempel fem sidor för fem punkter på listan, om de visas en i taget). Detta gör att man kan använda en sådan PDF för sig själv som en presentation under en föreläsning.

Automatisk byggnation och publicering på webben

Det är praktiskt när bilderna samlas automatiskt vid ändringar i versionskontrollsystemet, och ännu mer praktiskt när de automatiskt sammanställda bilderna publiceras på internet för allmän användning. Bilder från internet kan enkelt "spelats upp" för en publik från vilken maskin som helst som är ansluten till internet och projektorn.

Eftersom vi arbetar med GitHub, är ett naturligt val av CI-system TravisCI, och för hosting av avslutade presentationer — github.io. Idén med github.io är att allt statiskt innehåll som placeras i grenen gh-pages av ditt projekt på GitHub blir tillgängligt på adressen .gihub.io/.

Den fullständiga konfigurationsfilen för TravisCI, som inkluderar kompileringen av HTML-versionen av sidan med hjälp av Maven, konvertering till PDF med decktape och uppladdning av resultaten till grenen gh-pages för publicering på github.io, ser ut som så.

För att bygga ett sådant projekt på TravisCI-sidan måste miljövariablerna ställas in

GH_REF — ett värde av typen github.com/inponomarev/csa-hb
GH_TOKEN — en åtkomsttoken för GitHub. Den kan erhållas på GitHub i inställningarna för din profil, Developer Settings -> Personal Access Tokens. Om du publicerar presentationen i ett offentligt repository, räcker det att ange den enda åtkomstnivån "Access public repositories" för denna token.
GH_USER_EMAIL / GH_USER_NAME — ett par namn/e-post som kommer att användas för att göra ett push i grenen gh-pages.

Således leder varje kodcommit för presentationen på GitHub till en automatisk ombyggnad av bilderna i HTML- och PDF-format och deras återuppladdning på github.io. (Självklart bör man endast publicera de presentationer på github.io som man slutligen vill göra offentliga.)

Exempel på projekt

Slutligen — länkar till några exempelprojekt för presentationer med konfigurerade Maven-skript och CI-konfiguration för Travis-CI, som kan klonas och användas för att skapa egna presentationsprojekt: