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

Jag tror att jag har hållit dussintals presentationer för kollegor, kunder och föreläsningar under min karriär inom IT. I många år har Powerpoint varit mitt naturliga och pålitliga val för att göra diabilder. Men i år har situationen förändrats kvalitativt. Från februari till maj hade jag möjlighet att tala vid fem konferenser och bilderna till rapporterna skulle förberedas på kort tid, men av hög kvalitet. Frågan uppstod om att delegera den del av arbetet som rör den visuella utformningen av diabilder till andra. Jag försökte en gång arbeta 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 den "nyaste", och layouten "blev fel" på grund av de olika versionerna av Powerpoint och typsnitt på våra maskiner. Och jag bestämde mig för att prova något nytt. Jag provade det och sedan dess tror jag inte att jag kommer att gå tillbaka till Powerpoint.

Vad vi vill

För ungefär ett och ett halvt år sedan slutade vårt företag 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 ett litet dokument, när volymen ökar, uppstår svårigheter med samarbete och att få högkvalitativ och enhetlig design. Vårt val föll på AsciiDoctor, och vi slutar aldrig att vara glada över detta val, men det här är ett ämne för en separat artikel. Ungefär samtidigt lärde vi oss effektiviteten hos en av DevOps-principerna, "allt som kod", så valet av krav för en ny teknik för att skapa presentationsbilder var ganska uppenbart:

Presentationen måste vara en vanlig textfil i märkningsspråk.
Våra bilder handlar om utvecklingsprojekt, så uppmärkningen bör möjliggöra enkel insättning utan hjälp av externa system.
- kodavsnitt med syntaxmarkering,
- enkla diagram i form av geometriska former förbundna med pilar,
- UML-diagram, flödesscheman m.m.
Presentationsutkastet ska lagras i ett versionskontrollsystem.
Validering och montering av färdiga objektglas bör göras i CI-systemet.

Idag finns det två grundläggande alternativ för att skapa bilder i märkningsspråk: ett paket projektor för LaTeX eller något av ramverken för att skapa HTML/CSS-bilder (RevealJS, anmärkning, deck.js och många andra).

Även om mitt hjärta är i LaTeX, sa mitt sinne mig att valet av en lösning som jag inte skulle vara den enda som använder borde ligga på sidan av en lösning som är bekant för en bredare krets av människor. Alla känner inte till LaTeX, och om din dagliga praktik inte är relaterad till att skriva vetenskapliga artiklar, är det osannolikt att du kommer att hitta tid att fördjupa dig i det här systemets enorma, intrikata värld.

Kunskaper i HTML/CSS är dock inte en allmänt vanlig färdighet: till exempel är jag långt ifrån fullt skicklig i det. Lyckligtvis kommer här den redan välbekanta AsciiDoctor till undsättning: en omvandlare asciidoctor-avslöjar låter dig skapa RevealJS-bilder med AsciiDoctor-uppmärkning. Och det är lätt att lära sig och tillgängligt för alla!

Hur man kodar bilder

För att förstå essensen av bildkodning på AsciiDoctor är det enklast att ge specifika exempel. Alla dessa är från faktiska bilder som jag gjorde för mina konferenspresentationer i år.

Skjut med titel och lista i på varandra följande punkter:

== Зачем нам Streams API?

[%step]
* Real-time stream processing
* Stream-like API (map / reduce)
* Под капотом:
** Автоматический offset commit
** Ребалансировка
** Внутреннее состояние обработчиков
** Легкое масштабирование

Resultat

Rubrik och källkodsfragment med syntaxmarkering:

== Kafka Streams API: общая структура KStreams-приложения

[source,java]
----
StreamsConfig config = ...;
//Здесь устанавливаем всякие опции

Topology topology = new StreamsBuilder()
//Здесь строим топологию
....build();
----

Resultat

Under förberedelserna av ett föredrag är exempel på demokod föremål för upprepade revideringar och förbättringar, så möjligheten att snabbt kopiera och klistra in "råkod" direkt i en bild, vilket säkerställer att demoexemplet är uppdaterat och utan att behöva oroa dig för syntaxmarkering, är ovärderlig.

Rubrik, illustration och text (layout på bilden görs i celler) AsciiDoctor tabeller):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, November 2018
* Примеры кода для Kafka 1.0
|===

Resultat

Ibland behöver du ingen titel, och du behöver bara en helskärmsbild för att illustrera din poäng:

[%notitle]
== Жить в легаси нелегко

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

Resultat

Ofta behöver idén stödjas av ett enkelt diagram, i form av "rutor förbundna med pilar." Lyckligtvis är AsciiDoctor integrerad med systemet graphviz — ett språk som gör att man kan beskriva grafdiagram baserat på beskrivningen av hörn och sambanden mellan dem. Graphviz har en inlärningskurva, men baserat på exemplen förutsatt att det är ganska enkelt! Så här ser det ut:

== Пишем “Bet Totalling App”

Какова сумма выплат по сделанным ставкам, если сыграет исход?

[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;}
}
-----

Resultat

I de fall du behöver redigera en signatur på en figur, ändra riktning på en pil etc. kan du göra detta direkt i presentationskoden, istället för att rita om en bild någonstans och infoga den igen i bilden. Detta ökar avsevärt arbetshastigheten på rutschbanor.

Ett mer komplicerat exempel:

== Невоспроизводимая сборка
[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=<<font color="red">merge blocked</font>>]
  {rank = same; u; r0; b4;}
}
-----

Resultat

Förresten, det är bekvämt att experimentera med Graphviz och felsöka bilder på sidan Graphviz online.

Slutligen, om du behöver infoga ett flödesschema, klassdiagram eller annat standardiserat diagram i en bild, så kan i det här fallet ett annat system integrerat med AsciiDoctor komma till undsättning, PlantUML. Min kollega Nikolay Potashnikov skrev om PlantUMLs omfattande kapacitet separat inlägg.

Att konvertera ett presentationsprojekt till kod lagrad i ett versionskontrollsystem gör det möjligt att organisera ett samarbete kring presentationen, i första hand dela upp uppgifterna att skapa innehåll och design. Bilddesign (typsnitt, bakgrunder, marginaler) i RevealJS beskrivs med CSS. Min personliga skicklighet med CSS förmedlas bäst av denna gif – men det är inte läskigt när det finns människor som arbetar med CSS mycket mer skickligt och snabbare än jag. Slutresultatet är att med en snabbt närmande presentationsdeadline kan vi arbeta på olika filer samtidigt via Git och uppnå en samarbetshastighet som skulle vara omöjlig när vi skickar .pptx-filer via e-post.

Bygga en HTML-sida med bilder

Oformaterade textkällor är bra, men hur sammanställer du dem i själva presentationen?

AsciiDoctor är ett Ruby-projekt och kan köras på flera sätt. Först kan du installera Ruby-språket och köra asciidoctor direkt, vilket förmodligen är den mest välbekanta upplevelsen för Ruby-utvecklare.

Om du inte vill bry dig om att installera Ruby kan du använda en docker-bild asciidoctor/docker-asciidoctor, där du, när den startas, kan koppla en mapp till projektkällorna via VOLYM och få resultatet på den angivna platsen.

Alternativet jag valde kan verka lite oväntat, men det är det mest bekväma för mig som Java-utvecklare. Det kräver inte att Ruby eller Docker är installerat, men det låter dig generera bilder med hjälp av ett Maven-skript.

Saken är att projektet JRuby — Java-implementeringen av Ruby-språket är så bra att den låter dig köra nästan allt som skapats för Ruby på en Java-maskin, och att köra AsciiDoctor är en av de vanligaste användningsområdena för JRuby.

tillgänglighet asciidoctor-maven-plugin låter dig samla AsciiDoctor-dokumentation som är en del av ett Java-projekt (som vi aktivt använder). I det här fallet laddas AsciiDoctor och JRuby ned automatiskt av Maven, och AsciiDoctor körs i JRuby-miljön: ingenting behöver installeras på maskinen! (Förutom paketet graphviz, som behövs om du vill använda GraphViz- eller PlantUML-grafik.) Lägg bara dina .adoc-filer i mappen src/main/asciidoc/. här exempel på ett memo, samlar bilder med diagram.

Konvertera bilder till PDF

Även om HTML-versionen av bilderna är ganska självförsörjande, är det fortfarande nödvändigt att ha en PDF-version av bilderna. För det första händer det att på vissa konferenser som inte ger talaren möjlighet att ansluta sin egen bärbara dator kräver de bilder "enbart i pptx- eller pdf-format", utan att förvänta sig att de också kan vara i HTML. För det andra är det bra att skicka till arrangörerna en oredigerad version av dina bilder, som de visades i presentationen, i PDF-format för publicering i konferenshandlingarna.

Lyckligtvis kan verktyget Node.js hantera denna uppgift. däcktejp, byggd på grundval av Dockare — Chrome-webbläsarhanteringsautomationssystem. 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 för att lansera decktape som jag var tvungen att komma på genom trial and error:

upplösning via parameter -s det är nödvändigt att ställa in med dubbel reserv, annars kan det bli problem med konverteringsresultaten
i URL:en till HTML-versionen av presentationen måste du skicka en parameter ?fragments=true, vilket gör att du kan skapa en separat PDF-sida för varje mellanläge på din bild (till exempel fem sidor för fem listobjekt om de visas efter varandra). Detta gör att du kan använda en sådan PDF ensam som en presentation under en rapport.

Automatisk montering och publicering på webben

Det är bekvämt när bilder kompileras automatiskt när ändringar läggs in i versionskontrollsystemet, och ännu bekvämare när automatiskt kompilerade bilder läggs ut på Internet för allmänt bruk. Diabilder från Internet kan enkelt "spelas upp" för en publik från vilken maskin som helst som är ansluten till Internet och en projektor.

Eftersom vi använder GitHub i vårt arbete är det naturliga valet av CI-system TravisCI, och för att vara värd för färdiga presentationer - github.io. Tanken bakom github.io är att allt statiskt innehåll skickas till en gren gh-pages ditt projekt på GitHub blir tillgängligt på <ваше имя>.gihub.io/<ваш проект>.

En komplett TravisCI-konfigurationsfil som inkluderar att kompilera HTML-versionen av sidan med Maven, konvertera den till PDF med decktape och dumpa resultaten till en gren 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 du konfigurera miljövariabler

GH_REF — Värdet på formen github.com/inponomarev/csa-hb
GH_TOKEN — GitHub-åtkomsttoken. Du kan hämta det från GitHub i dina profilinställningar, Utvecklarinställningar -> Personliga åtkomsttokens. Om du lägger upp en presentation till ett offentligt arkiv räcker det för denna token att ange en enkel åtkomstnivå för "Åtkomst till offentliga arkiv".
GH_USER_EMAIL / GH_USER_NAME — ett namn/e-postpar på uppdrag av vilket trycket till tråden kommer att göras gh-pages.

På så sätt bygger varje commit av presentationskoden till GitHub automatiskt om bilderna i HTML- och PDF-format och laddar upp dem igen till github.io. (Naturligtvis bör du bara lägga upp på github.io de presentationer som du i slutändan vill göra offentliga.)

Projektexempel

Slutligen, här är länkar till ett par exempel på presentationsprojekt med konfigurerade Maven-skript och CI-konfiguration för Travis-CI, som du kan klona och använda när du skapar dina egna presentationsprojekt: