🥇Esitlused kui kood, või Miks ma enam Powerpoint'i ei kasuta

Tundub, et olen oma IT-karjääri jooksul teinud kümneid esitlusmaterjale kolleegidele, klientidele ja avalikeks esinemisteks. Palju aastaid oli Powerpoint minu jaoks loomulik ja usaldusväärne valik slaidide valmistamiseks. Kuid sel aastal muutus olukord dramaatiliselt. Februari ja mai vahel esinesin viiel konverentsil ning slaidid tuli valmistada kiiresti, kuid kvaliteetselt. Küsisin endalt, kuidas delegeerida visuaalse disaini osa teistele inimestele. Üks kord püüdsin töötada disaineriga, saates .pptx faile e-posti teel, kuid töö muutus kaoseks: keegi ei teadnud, milline versioon slaididest on "uusim", ja kujundus "kippus minema" meie arvutite Powerpointi versioonide ja fontide erinevuste tõttu. Ja otsustasin proovida midagi uut. Proovisin, ja sellest ajast alates ei mõtle ma tagasi Powerpointi peale.

Mida me soovime

Käibpoolteist aastat tagasi loobusime me ettevõttes Wordi kasutamisest projektidokumentatsiooni koostamiseks, seistes silmitsi nende samade probleemidega: kuigi Word on hea väikeste dokumentide koostamiseks, tekivad mahu suurenedes koostöö ja kvaliteetsete ning ühtsete vormindamisraskustega. Meie valik langes AsciiDoctor, mille üle me ei lakka rõõmustamast, kuid see on eraldi teema. Umbes sel ajal avastasime ühe DevOps-printsiibi efektiivsuse "kõik on kood" ning seetõttu oli uue esitlusdiatoodete tehnoloogia nõuete valik üsna ilmne:

Esitlus peab olema puhtteksti fail märgistuskeeles.
Meie slaidid käsitlevad arendusprojekte, seega peab märgistus võimaldama hõlpsasti, ilma väliste süsteemide abita, sisestada
- kodeeritud fragmente süntaksi esitlemisega,
- lihtsaid diagramme geomeetriliste kujundite ja nende vaheliste nooltega,
- UML-diagramme, vooskeeme jne.
Esitluse projekt peab olema versioonihaldussüsteemis.
Valideerimine ja valmis slaidide kogumine peab toimuma CI-süsteemis.

Praegu on kaks põhilist võimalust slaidide loomiseks märgistuskeeltes: pakett beamer LaTeX-i jaoks või mõni HTML/CSS slaidide loomise raamistik (RevealJS, remark, deck.js ja paljusid teisi).

Kuigi mu südames on LaTeX, ütles mõistus, et lahenduse valik, millega ma ei jää üksi, peaks olema tuntuma lahenduse poole. LaTeXi ei tunne kõik ja kui teie igapäevane praktika ei ole teadusartiklite kirjutamisega seotud, siis tõenäoliselt ei ole teil aega selle keerulise süsteemi süvitsi minemiseks.

Siiski ei ole ka HTML/CSS valdamine just laialdaselt levinud oskus: mina näiteks ei valda seda täielikult. Õnneks tuleb appi juba tuttav AsciiDoctor: konverter asciidoctor-revealjs mis võimaldab luua RevealJS slaide, kasutades AsciiDoctor'i märgistuskeelt. Ja see on tõepoolest lihtne õppida ja kõigile kergesti kättesaadav!

Kuidas slaide kodeerida

Slaidide kodeerimise olemuse mõistmiseks on kõige lihtsam tuua konkreetsed näited. Kõik need on reaalsed slaidid, mille ma olen teinud oma konverentsiettekannete jaoks sel aastal.

Pealkirjaga slaid ja loetelu, kus punktid avanevad üksteise järel:

== Miks on meil vaja Streams API-d?

[%step]
* Reaalaja voogude töötlemine
* Voogudele sarnane API (map / reduce)
* Tarkvaras:
** Automaatne offset'i kinnitamine
** Uuesti tasakaalustamine
** Töötlejate sisemine olek
** Lihtne skaleerimine

Tulemus

Pealkiri ja koodilõik, millel on süntaksihõlma:

== Kafka Streams API: KStreams-rakenduse üldstruktuur

[source,java]
----
StreamsConfig config = ...;
//Siin seadistame erinevaid valikuid

Topology topology = new StreamsBuilder()
//Siin ehitame topoloogia
....build();
----

Tulemus

Ettevalmistuse käigus esitlusele (demo) koodinäited läbivad pidevalt ümbertegemisi ja täiustusi, seetõttu on ääretult väärtuslik võimalus kiiresti «toore koodi» slaidile kopeerida ja kleepida, tagades demo näite ajakohasuse ilma süntaksihõlma pärast muretsemata.

Pealkiri, illustreeriv pilt ja tekst (slaidi paigutust teeme AsciiDoctori tabelites tabelis):

== Kafka Streams Action'is

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams Action'is”, november 2018
* Koodinäited Kafka 1.0 jaoks
|===

Tulemus

Mõnikord pealkiri pole vajalik, ja sinu mõtte illustreerimiseks on lihtsalt vajalik suur pilt:

[%notitle]
== Elu legacy's in the hard

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

Tulemus

Sageli on mõte vajalik toetada lihtsa diagrammiga, kujul "kastid, mis on ühendatud nooltega". Õnneks on AsciiDoctor integreeritud süsteemiga Graphviz — keel, mis võimaldab kirjeldada graafdiagramme täppide ja nendevaheliste seoste põhjal. Graphvizi kasutamine nõuab harjutamist, kuid olemasolevate näidiste pealt on seda üsna lihtne õppida! Nii see välja näeb:

== Kirjutame "Bet Totalling App"

Mis on panuste summa, kui tulemus läheb korda?

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

Tulemus

Kui on vajalik kujutise sildi redigeerimine, noole suuna muutmine jms — saab seda teha otse esituse koodis, selle asemel et joonistada kuskil pilt ümber ja uuesti slaidile lisada. See kiirus tõstab oluliselt slaidide töötamise efektiivsust.

Näide keerulisem:

== Reproduktiivne kogumik
[graphviz, "unstable-update.png"]
-----
digraph G {
  rankdir="LR";
  graph [ dpi = 150 ];
  u -> r0;
  u[shape=plaintext; label="linter updaten+ 13 hoiatused"]
  r0[shape=point, width = 0]
  r1 -> r0[ arrowhead = none, label="master branch" ];
  r0-> r2 [];   b1 -> b4;  r1->b1
  r1[label="150nhoiatused"]
  b1[label="± 0nhoiatused"]
  b4[label="± 0nhoiatused"]
  b4->r2
  r2[label="163nhoiatused", color="red", xlabel=<ühendamine blokeeritud>]
  {rank = same; u; r0; b4;}
}
-----

Tulemus

Muide, eksperimenteerimine Graphviziga ja piltide silumine on mugav lehe peal Graphviz veebis.

Lõpuks, kui on vaja lisada slaidi vooskeemi, klassidiagrammi või mõne muu standarditud diagrammi, siis selle puhul võib abiks olla veel üks AsciiDoctoriga integreeritud süsteem, PlantUML. PlantUML-i ulatuslike võimaluste kohta on mu kolleeg Nikolai Potashnikov kirjutanud erineva postituse.

Prezentatsiooni projekti muutmine koodiks, mis salvestatakse versioonihaldussüsteemi, võimaldab korraldada koostööd presentatsiooniga, eeskätt jagades sisuloomise ja kujundamise ülesandeid. Slaidide kujundamine (kirj fonts, taustad, vahed) RevealJS-is kirjeldatakse CSS-i abil. Minu isiklik oskus CSS-iga toimetada antud kontekstis edastatakse kõige paremini selle gifiga — aga see pole hirmutav, kui on inimesi, kes töötavad CSS-i kallal palju osavamalt ja kiiremini kui mina. Lõpuks tähendab see, et kiirelt läheneva esitluskuupäeva tingimustes saame töötada samaaegselt erinevate failide kallal Git'i abil ja suurendada koostöö kiirus, mis oleks võimatu, kui jagada faile .pptx e-postiga.

HTML-lehe koostamine slaididega

Tavalised tekstifailid on suurepärased, kuid kuidas need esitluseks kokku panna?

AsciiDoctor on Ruby keeles kirjutatud projekt, mida saab käivitada mitmel moel. Esiteks, võite installida Ruby keele ja käivitada asciidoctor otse, mis tõenäoliselt sobib kõige rohkem Ruby arendajatele.

Kui te ei soovi Ruby installimisega vaeva näha, võite kasutada docker-pilti asciidoctor/docker-asciidoctor, mille käivitamisel saate VOLUME kaudu ühendada projekti lähtefailide kausta ja määratud kohas tulemuse saada.

Variant, millele ise jäin, võib tunduda veidi ootamatu, kuid see on mulle Java arendajana kõige mugavam. See ei nõua Ruby installimist ega dockerit, kuid võimaldab slaide genereerida Maven-skripti abil.

Asi on nii, et projekt JRuby — Ruby keele Java rakendus — on nii hea, et võimaldab käivitada Java masinas praktiliselt kõike, mis on loodud Ruby jaoks, ning AsciiDoctori käitamine on üks JRuby kõige levinumaid rakendusi.

Olemasolu asciidoctor-maven-plugin aitab kokku panna AsciiDoctori dokumentatsiooni, mis on osa Java projektist (mida me aktiivselt kasutame). Samuti laaditakse AsciiDoctor ja JRuby Maven'i kaudu automaatselt alla ning AsciiDoctor käivitub JRuby keskkonnas: ei ole vaja midagi masinale installida! (Välja arvatud pakett graphviz, mis on vajalik, kui soovite kasutada GraphVizi või PlantUML-i graafikat.) Piisab, kui asetate oma .adoc-failid kausta src/main/asciidoc/. Siin näidis monument, mis kogub slaide diagrammidega.

Slaidide konverteerimine PDF-iks

Kuigi HTML-i vorming esitluspiltidest on täiesti iseseisev, on vahel siiski vajalik omada ka PDF-vormi. Esiteks juhtub, et mõnedes konverentsides, mis ei paku esinejale võimalust oma sülearvutit ühendada, nõutakse slaide "rangelt vormingus pptx või pdf", unustades, et need võivad olla ka HTML formaadis. Teiseks on hea, et saata korraldajatele teie slaidide muutumatu versioon sellisena, nagu need esitluse ajal näidati, PDF vormingus konverentsi materjalide avaldamiseks.

Õnneks tegeleb selle probleemiga Node.js utiliit decktape, mis on ehitatud Puppeteer — Chrome'i brauseri automaatse juhtimise süsteemi baasil. RevealJS esitluse PDF-iks konvertimiseks saab kasutada käsku

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

Kaks nipi decktape'i käivitamisel, millele tuli jõuda katse-eksituse meetodil:

resolutsioon läbi parameetri -s tuleb seadistada kahekordse varu üle, vastasel juhul võivad konverteerimisega olla probleemid.
HTML-versiooni esitluse URL-is tuleb edastada parameeter ?fragments=true, mis võimaldab luua iga slaidi vahepealse oleku jaoks eraldi PDF-lehe (näiteks viis lehte viie punkti loendi jaoks, kui need kuvatakse üksteise järel). See võimaldab kasutada sellist PDF-d iseseisvalt esitlusena esinemisel.

Automaatne koostamine ja avaldamine veebis

On mugav, kui slaidid koostatakse automaatselt, kui muudatused jõuavad versioonihaldussüsteemi, ja veelgi mugavam on, kui automaatselt koostatud slaidid avaldatakse internetis üldiseks kasutamiseks. Internetis olevaid slaide saab hõlpsasti "esitada" publikule igalt seadmel, mis on internetiga ja projektoriga ühendatud.

Kuna me kasutame oma töös GitHubi, on loogiline valik CI-süsteemiks TravisCI, ja valmis esitlustena hostimiseks — github.io. GitHubi idee on see, et igasugune staatiline sisu, mis on paigutatud teie projekti harusse gh-pages , on saadaval aadressil .gihub.io/.

Täielik TravisCI konfiguratsioonifail, mis hõlmab lehe HTML versiooni kompileerimist Maveniga, PDF-i konverteerimist decktape'i abil ja tulemuste laadimist harusse gh-pages publikatsiooniks github.io, näeb välja nagu nii.

Selle projekti kogumiseks TravisCIs on vajalik keskkonnamuutujate seadistamine

GH_REF — väärtus vormingus github.com/inponomarev/csa-hb
GH_TOKEN — GitHub'i juurdepääsutoken. Selle saab hankida oma GitHubi profiili seadetes, Developer Settings -> Personal Access Tokens. Kui laadite esitlust avalikku hoidlasse, piisab, kui määrata sellele tokenile ainult üks juurdepääsutase „Access public repositories”.
GH_USER_EMAIL / GH_USER_NAME — paar nimi/e-post, mille nimel toimub haru tõukamine gh-pages.

Nii toimib iga esituse koodi commit GitHubis automaatse slaidide uuesti koostamise ja nende laadimisega HTML ja PDF formaatides github.io-le. (Muidugi tuleks github.io-le laadida ainult need esitused, mida soovite lõpuks avalikku teha.)

Projektide näited

Lõpetuseks — lingid paarile näitprojekti esitlusest, millel on seadistatud Maven-skripti ja CI-konfiguratsioon Travis-CI jaoks, mida saab kloonida ja kasutada oma esitluste loomisel: