🥇Ettekanne kui kood, või Miks ma enam ei kasuta Powerpointi

Tundub, et olen oma IT-karjääri jooksul pidanud tegema kümneid esitlust kolleegidele, klientidele ja avalikke kõnesid. Paljude aastate jooksul oli PowerPoint minu jaoks loomulik ja usaldusväärne valik slaidide loomiseks. Kuid sel aastal muutus olukord oluliselt. Kõikide veebikonverentside korral oleks mul veebruarist maini olnud viis ettekannet, ja slaidid pidid olema kvaliteetselt ning lühikese ajaga valmis. Tõstatus küsimus delegeerimise kohta, mis puudutas slaidide visuaalset disaini teistele inimestele. Kord proovisin töötada disaineriga, edastades .pptx faile e-posti teel, kuid töö muutus kaoseks: keegi ei teadnud, milline slaidide versioon on „uusim”, ja vormindamine „läks ära”, sest PowerPointi versioonide ja meie masinatel olevate fondide erinevused tekitasid probleeme. Otsustasin proovida midagi uut. Proovisin ja sellest ajast peale ei mõtle ma tagasi PowerPointile.

Mida me soovime

Kumbki poolteist aastat tagasi loobusime ettevõttes Wordi kasutamisest projektidokumentatsiooni loomisel, silmitsi seistes sama probleemiga: kuigi Word on hea väikeste dokumentide koostamiseks, tekivad mahukamaid dokumente luues raskused koostöö ja kvaliteetse ning ühtse vormistuse saavutamisel. Meie valik langes AsciiDoctor, ja me ei lakka selle üle rõõmustamast, kuid see on teema eraldi artikli jaoks. Umbes sel ajal mõistsime ühe DevOps-põhimõtte „kõik on kood” efektiivsust, seega oli slaidide loomiseks uue tehnoloogia valik üsna ilmne:

Esitlus peab olema tavaline tekstifail märgistuskeeles.
Meie slaidid käsitlevad arendusprojekte, seega peab märgistus võimaldama hõlpsasti, ilma väliste süsteemide abita, lisada
- koodilõike süntaksi rõhutamisega,
- lihtsaid diagramme geomeetriliste kujundite kujul, mis on ühendatud nooltega,
- UML-diagramme, vooskeeme ja muud.
Esitluse projekt peab olema versioonihalduse süsteemis.
Valideerimine ja valmis slaidide koostamine peab toimuma CI-süsteemis.

Tänapäeval on kahte põhivõimalust slaidide loomiseks märgistuskeeltes: paketid beamer LaTeXile või mõni raamistiku, et luua slaide HTML/CSSiga (RevealJS, remark, deck.js ja paljusid teisi).

Kuigi mu hing kaldub LaTeX-i poole, ütles mõistus, et pean valima lahenduse, mida kasutan mitte ainult mina, vaid ka teised. LaTeX ei ole kõigile tuttav ja kui teie igapäevane praktika ei ole seotud teadusartiklite kirjutamisega, siis tõenäoliselt ei leia te aega, et sukelduda selle süsteemi tohutusse ja keerukasse maailma.

Sellegipoolest ei ole HTML/CSS oskus ka just kõige levinum: mina ei valda seda kaugeltki täielikult. Õnneks tuleb appi juba tuttav AsciiDoctor: konverter, asciidoctor-revealjs mis võimaldab luua RevealJS esitlusi, kasutades AsciiDoctor-i märgendust. Ja see on tõesti lihtne õppida ja kergesti kättesaadav igaühele!

Kuidas slaide kodeerida

Slaidide kodeerimise olemuse mõistmiseks on kõige lihtsam tuua konkreetsed näited. Kõik need on reaalsed slaidid, mida ma tegin selle aasta oma konverentsil esitluste jaoks.

Slaid koos pealkirja ja järjestikku avanevate punktidega:

== Miks on meil vaja Streams API-d?

[%step]
* Reaalajas voogude töötlemine
* Voolu-sarnane API (map / reduce)
* Tagaküljel:
** Automaatne offset commit
** Taaskaalumine
** Töötlejate sisemine olek
** Lihtne skaleerimine

Tulemus

Pealkiri ja koodilõik süntaksi rõhutamisega:

== Kafka Streams API: KStreams rakenduse üldine struktuur

[source,java]
----
StreamsConfig config = ...;
// Siin seadistame erinevad valikud

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

Tulemus

Esitluse ettevalmistamise protsessis läbivad demonstreerimisnäited koodi korduvalt muutmise ja täiustamise, seetõttu on hindamatu võimalus kiiresti kopeerida ja kleebida "toores kood" otse slaidile, tagades demonstratsiooni näite ajakohasuse ja mitte muretsedes süntaksi rõhutamise pärast.

Pealkiri, illustreeriv pilt ja tekst (slaidi paigutus toimub AsciiDoctori tabeli rakkudes)):

== Kafka Streams Action'is

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
"Kafka Streams Action", november 2018
* Koodi näited Kafka 1.0
|===

Tulemus

Mõnikord ei ole pealkiri vajalik, vaid lihtsalt pilt, mis illustreerib teie mõtet ja katab kogu ekraani:

[%notitle]
== Elamine legacy-s ei ole lihtne

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

Tulemus

Tihti on mõtte toetamiseks vajalik lihtne diagramm, milles "ruudud, mis on ühendatud nooledega". Õnneks on AsciiDoctor integreeritud süsteemiga Graphviz — keele, mis võimaldab kirjeldada graafikute diagramme, lähtudes sõlmede ja nendevaheliste seoste kirjeldust. Graphviz'i on vaja õppida, kuid olemasolevate näidiste põhjal on see üsna lihtne! Nii see välja näeb:

== Kirjutame "Bet Totalling App"

Milline on maksete summa tehtud panuste põhjal, kui tulemus mängib?

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

Tulemus

Kui on vajalik diagrammi märgistus redigeerida, noole suunda muuta jne, siis saab seda teha otse esituse koodis, selle asemel, et joonistada pilti uuesti ja lisada see slaidi. See tõhustab slaidide koostamiseks vajalikku aega.

Veidi keerulisem näide:

== Reproduseerimata kogumine
[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;}
}
-----

Tulemus

Muide, Graphviz'iga katsetamine ja piltide silumine on mugav saidil Graphviz online.

Lõpuks, kui on vajalik slaidi lisada vooskeem, klassidiagramm või muu standardiseeritud diagramm, võib abiks olla veel üks AsciiDoctor'iga integreeritud süsteem, PlantUML. PlantUML-i ulatuslike võimaluste kohta on mu kolleeg Nikolai Potashnikov kirjutanud eraldi postituse.

Esitlusprojekti muutmine versioonihaldussüsteemi salvestatud koodiks võimaldab korraldada koostööd esitamise üle, eelkõige jagada sisu loomise ja kujundamise ülesandeid. Slaidide kujundamine (fondid, taustad, vahed) RevealJS-is kirjeldatakse CSS-i abil. Minu isiklik oskus CSS-i kasutada edastab kõige paremini see gif — kuid see ei ole hirmutav, kui on inimesi, kes töötavad CSS-i kallal palju osavamalt ja kiiremini kui mina. Lõppkokkuvõttes saame esituse tähtaega lähenedes samal ajal töötada erinevate failide kallal läbi Git'i ja suurendada koostöö kiirus, mida me ei saaks saavutada .pptx-failide e-postiga saatmise kaudu.

HTML-lehe koostamine slaididega

Lihtne tekst-allergewær — see on suurepärane, kuid kuidas neid esitluseni koondada?

AsciiDoctor on Ruby keeles kirjutatud projekt ja selle käivitamiseks on mitmeid võimalusi. Esiteks saate installida Ruby ja käivitada asciidoctor otse, mis on ilmselt kõige lähsem Ruby arendajatele.

Kui ei soovi Ruby installimisega tegeleda, saate kasutada docker-pilti asciidoctor/docker-asciidoctor, mille käivitamisel saab VOLUME abil ühendada projekti lähtefailide kausta ja määratud kohas saada tulemuse.

Variant, mille peale mina jään, võib tunduda veidi ootamatu, kuid see on mulle Java-arendajana kõige mugavam. See ei nõua ei Ruby installimist ega docker'i olemasolu, kuid võimaldab genereerida slaide Maven-skripti abil.

Asi on selles, et projekt JRuby — Java-implementatsioon Ruby keelest — on nii hea, et võimaldab Java-juhis käitada praktiliselt kõike, mis on loodud Ruby jaoks, ja AsciiDoctori käitamine on üks JRuby kõige levinumaid rakendusi.

Standardsete moodulite komplekti olemasolu asciidoctor-maven-plugin võimaldab koostada AsciiDoctori dokumentatsiooni, mis on osa Java projektist (mida me aktiivselt kasutame). Samuti allalaadib Maven automaatselt AsciiDoctori ja JRuby ning AsciiDoctor käib JRuby keskkonnas: midagi ei pea teie masinasse installima! (Välja arvatud pakett graphviz, mis on vajalik, kui soovite kasutada graafikat GraphViz või PlantUML.) Piisab, kui asetate oma .adoc-failid kausta src/main/asciidoc/. Siin näide monument, mis kogub slaide diagrammidega.

Slaidide konverteerimine PDF-ks

Kuigi slaidide HTML-versioon on täiesti iseseisev, on siiski vajalik, et PDF-versioon slaididest oleks samuti olemas. Esiteks võib juhtuda, et mõnedes konverentsides, kus esinejale ei anta võimalust oma sülearvutit ühendama, nõutakse slaide "rangelt pptx või pdf formaadis", eeldades, et need võivad olla ka HTML-is. Teiseks on hea komme saata korraldajatele teie slaidide muutumatu versioon just sellisena nagu need ettekanne ajal näidati, PDF-formaadis konverentsi materjalide avaldamiseks.

Õnneks teeb selle ülesande täitmiseks ära Node.js utiliit decktape, mis põhineb Puppeteeril — Chrome'i brauseri automaatika süsteemil. RevealJS esitlust PDF-ks konverteerimiseks võib kasutada käsku

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

Kaks nippi decktape'i käivitamisel, mille poole ma kogemata jõudsin:

resolutsioon parameetri kaudu -s tuleks seada kahekordse varuga, vastasel juhul võivad konverteerimise tulemustes esineda probleemid.
HTML-versiooni URL-is tuleb edastada parameeter. ?fragments=true, mis võimaldab luua iga teie slaidi vahepealse oleku jaoks eraldi PDF-lehe (näiteks viis lehte viie loendi punkti jaoks, kui need kuvatakse üksikult). See võimaldab sellist PDF-i kasutada iseseisvalt esitlusena ettekande ajal.

Automaatne koostamine ja avaldamine veebis.

On mugav, kui slaidid koostatakse automaatselt, kui muudatused sisenevad versioonihaldussüsteemi, ja veelgi mugavam, kui automaatselt koostatud slaidid avaldatakse internetis kõigile kasutamiseks. Internetist pärit slaide saab hõlpsasti „esitada” publikule mis tahes arvutist, mis on ühendatud internetiga ja projektoriga.

Kuna me kasutame töös GitHubi, siis on loogiline valik CI-süsteemi jaoks TravisCI, ja valmis esitluste majutamiseks — github.io. Ideoloogia github.io seisneb selles, et iga staatiline sisu, mis paigutatakse teie GitHubi projekti harusse gh-pages , on kergesti juurdepääsetav aadressil .gihub.io/.

Täielik TravisCI konfiguratsioonifail, mis sisaldab HTML-versiooni lehe koostamist Maveniga, konverteerimist PDF-ks decktape abil ja tulemuste üleslaadimist harusse gh-pages avaldamiseks github.io, näeb välja nii.

Selle projekti koostamiseks TravisCIs tuleb seadistada keskkonna muutujad

GH_REF — väärtus kujul github.com/inponomarev/csa-hb
GH_TOKEN — GitHubi juurdepääsu token. Saa see GitHubis oma profiili seadetes, Developer Settings -> Personal Access Tokens. Kui laadite esitlust üles avalikku repositoriisse, piisab selle tokeni jaoks, kui määrate ainult ühe juurdepääsu taseme "Access public repositories".
GH_USER_EMAIL / GH_USER_NAME — paar nimi/e-post, mille alt toimub push harusse gh-pages.

Seega toob iga esitluskaidi koodikommit GitHubis automaatse slaidide uuesti koostamise HTML- ja PDF-formaatides ning nende uuesti üleslaadimise github.io. (Muidugi tuleks github.io-sse üles laadida ainult need esitlus, mida soovite lõpuks avalikuks teha.)

Projektide näited

Lõpetuseks — lingid paarile näitele projektidest, kus on seadistatud Maven-skriptid ja CI-konfiguratsioon Travis-CI jaoks, mida saab kloonida ja kasutada oma projektide loomiseks: