🥇Prezentare ca și cod, sau De ce nu mai folosesc Powerpoint

Se pare că am avut ocazia să fac zeci de prezentări pentru colegi, clienți și în cadrul unor apariții publice de-a lungul carierei mele în IT. Mulți ani, PowerPoint a fost pentru mine o alegere naturală și de încredere pentru crearea slide-urilor. Dar anul acesta, lucrurile s-au schimbat semnificativ. Între februarie și mai, am avut ocazia să vorbesc la cinci conferințe și a trebuit să pregătesc slide-urile pentru prezentări într-un timp scurt, dar cu calitate. A apărut întrebarea de a delega partea de lucru referitoare la designul vizual al slide-urilor altor persoane. Odată am încercat să colaborez cu un designer, trimițând fișiere .pptx prin e-mail, dar munca s-a transformat într-un haos: nimeni nu știa care versiune a slide-urilor era „cea mai nouă”, iar formatarea „s-a stricat” din cauza diferențelor între versiunile PowerPoint și fonturile de pe calculatoarele noastre. Așa că am decis să încerc ceva nou. Am încercat și de atunci nu mă mai gândesc să revin la PowerPoint.

Ce ne dorim

Cu aproximativ un an și jumătate în urmă, compania noastră a renunțat la utilizarea Word pentru crearea documentației de proiect, confruntându-se cu aceleași probleme: deși Word este bun pentru a redacta un document mic, pe măsură ce volumul crește, apar dificultăți în colaborarea comună și obținerea unui aspect calitativ și unificat. Alegerea noastră a fost AsciiDoctor, iar de această alegere nu încetăm să ne bucurăm, dar aceasta este o temă pentru un articol separat. Aproape în aceeași perioadă, am învățat despre eficiența unuia dintre principiile DevOps „totul ca și cod”, astfel încât alegerea cerințelor pentru noua tehnologie de creare a slide-urilor a fost destul de evidentă:

Prezentarea ar trebui să fie un fișier plain text în limbaj de marcare.
Slide-urile noastre se referă la proiecte de dezvoltare, așa că markup-ul ar trebui să permită inserarea ușoară, fără a apela la sisteme externe, de
- fragmente de cod cu iluminare sintactică,
- diagrame simple sub formă de figuri geometrice conectate prin săgeți,
- diagrame UML, diagrame de flux și altele.
Proiectul prezentării ar trebui să fie stocat într-un sistem de control al versiunilor.
Validarea și compilarea slide-urilor finale ar trebui să fie realizate într-un sistem CI.

În prezent, există două opțiuni de bază pentru crearea slide-urilor în limbaje de marcare: pachetul beamer pentru LaTeX sau unul dintre framework-urile pentru crearea slide-urilor în HTML/CSS (RevealJS, remark, deck.js și multe altele).

Deși sufletul meu tinde spre LaTeX, rațiunea îmi sugerează că alegerea unei soluții pe care o voi folosi împreună cu alții ar trebui să fie în favoarea unei soluții cunoscute unui public mai larg. Nu toată lumea știe LaTeX, iar dacă practica ta zilnică nu implică scrierea de articole științifice, atunci este puțin probabil să ai timp să te adâncești în imensa și complicata lume a acestui sistem.

Cu toate acestea, cunoștințele de HTML/CSS nu sunt exact abilități răspândite: de exemplu, eu nu le stăpânesc complet. Din fericire, aici intervine deja cunoscutul nostru AsciiDoctor: un convertor asciidoctor-revealjs care permite crearea de slide-uri RevealJS folosind markup-ul AsciiDoctor. Iar acesta este simplu de învățat și accesibil tuturor!

Cum să codifici slide-urile

Pentru a înțelege esența codificării slide-urilor în AsciiDoctor, cel mai simplu este să oferim exemple concrete. Toate acestea sunt din slide-uri reale pe care le-am făcut pentru prezentările mele de la conferințe anul acesta.

Slide cu un titlu și o listă de puncte care apar unul câte unul:

== De ce avem nevoie de Streams API?

[%step]
* Procesare a fluxurilor în timp real
* API de tip flux (map / reduce)
* Sub capotă:
** Commit automat al offset-ului
** Reechilibrare
** Starea internă a procesatorilor
** Scalare ușoară

Rezultatul

Titlu și fragment de cod sursă cu evidențierea sintaxei:

== Kafka Streams API: structura generală a aplicației KStreams

[source,java]
----
StreamsConfig config = ...;
// Aici setăm diverse opțiuni

Topology topology = new StreamsBuilder()
// Aici construim topologia
....build();
----

Rezultatul

În procesul de pregătire pentru prezentare, exemplele demonstrative de cod suferă numeroase modificări și îmbunătățiri, așa că este neprețuită posibilitatea de a copia și lipi rapid „codul brut” direct în slide, asigurând astfel actualitatea exemplului demonstrativ fără a ne preocupa de evidențierea sintaxei.

Titlu, ilustrare și text (distribuția pe slide o facem în celulele tabelului AsciiDoctor):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, Noiembrie 2018
* Exemple de cod pentru Kafka 1.0
|===

Rezultatul

Uneori, titlul nu este necesar, iar pentru ilustrarea gândului tău este suficientă o imagine pe întreaga pagină:

[%notitle]
== A trăi în moștenire nu este ușor

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

Rezultatul

Adesea, gândul trebuie susținut cu o diagramă simplă, sub formă de „căsuțe conectate cu săgeți”. Din fericire, AsciiDoctor este integrat cu sistemul Graphviz — o limbaj care permite descrierea diagramelor grafice pe baza descrierii vârfurilor și legăturilor dintre acestea. Graphviz trebuie să fie stăpânit, dar pe baza exemplelor existente este destul de ușor de realizat! Iată cum arată:

== Scriem „Aplicația de totalizare a pariurilor”

Care este suma plăților pentru pariurile realizate, dacă rezultatul este câștigător?

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

Rezultatul

În cazul în care este necesar să editați eticheta de pe figură, să schimbați direcția săgeții etc. — acest lucru se poate face direct în codul prezentării, în loc să redesenezi imaginea undeva și să o insertezi din nou în diapozitiv. Acest lucru crește semnificativ rapiditatea muncii asupra diapozitivelor.

Un exemplu mai complex:

== Construire nereproductibilă
[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;}
}
-----

Rezultatul

Apropo, este convenabil să experimentați cu Graphviz și să debugați imaginile pe pagina Graphviz online.

În cele din urmă, dacă trebuie să inserați în diapozitiv un flux de lucru, o diagramă de clase sau o altă diagramă standardizată, atunci în acest caz vă poate ajuta un alt sistem integrat cu AsciiDoctor, PlantUML. Despre posibilitățile extinse ale PlantUML, colegul meu Nikolai Potashnikov a scris o postare separată.

Transformarea proiectului de prezentare într-un cod stocat pe un sistem de control al versiunilor permite organizarea muncii colaborative asupra prezentării, în primul rând împărțind sarcinile de creare a conținutului și designului. Designul diapozitivelor (fonturi, fundaluri, margini) în RevealJS este descris folosind CSS. Abilitatea mea personală de a gestiona CSS se transmite cel mai bine această gif. — dar nu este un lucru teribil când există oameni care lucrează cu CSS mult mai rapid și mai eficient decât mine. În final, se dovedește că, în condițiile unui termen limită care se apropie rapid pentru prezentare, putem lucra simultan la fișiere diferite prin Git și putem îmbunătăți rapiditatea colaborării, ceva ce nu este posibil prin trimiterea fișierelor .pptx prin e-mail.

Construcția unei pagini HTML cu diapozitive

Fișierul sursă este grozav, dar cum să-l compilezi într-o prezentare?

AsciiDoctor este un proiect scris în Ruby și poate fi pornit în mai multe moduri. În primul rând, poți instala limbajul Ruby și să rulezi asciidoctor direct, ceea ce, probabil, va fi cea mai familiară metodă pentru dezvoltatorii Ruby.

Dacă nu vrei să te ocupi de instalarea Ruby, poți folosi imaginea docker asciidoctor/docker-asciidoctor, în care, la pornire, poți conecta un folder cu fișierele sursă ale proiectului prin VOLUME și vei obține rezultatul într-un loc definit.

Varianta pe care am ales-o eu poate părea puțin surprinzătoare, dar este cea mai convenabilă pentru mine ca dezvoltator Java. Nu necesită nicio instalare a Ruby-ului și nu este nevoie de docker, dar permite generarea diapozitivelor printr-un script Maven.

Ideea este că proiectul JRuby — implementarea Java a limbajului Ruby — este atât de bun, încât permite rularea în mașina Java practic a tot ce a fost creat pentru Ruby, iar rularea AsciiDoctor-ului este una dintre cele mai frecvente aplicații ale JRuby.

Prezența asciidoctor-maven-plugin permite construirea documentației AsciiDoctor care este parte din proiectul Java (de care noi profităm activ). În acest caz, AsciiDoctor și JRuby sunt descărcate automat de Maven, iar AsciiDoctor este executat în mediu JRuby: nu trebuie să instalezi nimic pe mașină! (Cu excepția pachetului graphviz, care este necesar dacă dorești să utilizezi grafica GraphViz sau PlantUML.) Este suficient să plasezi fișierele tale .adoc în folderul src/main/asciidoc/. Iată exemplu de monument, ce generează diapozitive cu diagrame.

Conversia diapozitivelor în PDF

Deși versiunea HTML a diapozitivelor este complet autonomă, totuși, este uneori necesar să ai și o variantă PDF a diapozitivelor. În primul rând, în unele conferințe, care nu oferă vorbitorului posibilitatea de a conecta propriul laptop, se cere ca diapozitivele să fie „strict în format pptx sau pdf”, neșteptând să existe și în HTML. În al doilea rând, un bun obicei este să trimiți organizatorilor o variantă neschimbată a diapozitivelor tale așa cum au fost prezentate în cadrul raportului, în format PDF pentru publicarea fișierului în materialele conferinței.

Din fericire, pentru această sarcină există utilitarul Node.js decktape, construit pe baza Puppeteer — sistem de automatizare a controlului browserului Chrome. Pentru a converti o prezentare RevealJS în PDF, poți folosi comanda

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

Două trucuri pentru a rula decktape, la care am ajuns prin încercări și erori:

rezoluția prin parametru -s trebuie să aloci un rezervor dublu, altfel pot apărea probleme cu rezultatele conversiei
în URL-ul versiunii HTML a prezentării trebuie să transmiți parametrul ?fragments=true, ceea ce va permite crearea unei pagini PDF separate pentru fiecare stare intermediară a diapozitivului tău (de exemplu, cinci pagini pentru cinci puncte ale listei, dacă acestea sunt prezentate una câte una). Acest lucru va permite utilizarea acestui PDF ca atare pentru prezentare în timpul unei discursuri.

Compilare și publicare automată pe web

Este convenabil când diapozitivele sunt compilate automat atunci când apar modificări în sistemul de control al versiunilor, și chiar mai convenabil când diapozitivele compilate automat sunt publicate pe internet pentru utilizare generală. Diapozitivele de pe internet pot fi ușor „rulate” în fața audienței de pe orice mașină conectată la internet și proiector.

Dat fiind că folosim GitHub în activitatea noastră, o alegere naturală pentru CI este TravisCI, iar pentru găzduirea prezentărilor finalizate — github.io. Ideea github.io este că orice conținut static plasat în ramura gh-pages a proiectului tău pe GitHub devine accesibil la adresa .gihub.io/.

Fișierul de configurare complet TravisCI, care include compilarea versiunii HTML a paginii folosind Maven, conversia în PDF cu ajutorul decktape și încărcarea rezultatelor în ramura gh-pages pentru publicare pe github.io, arată . Cu ajutorul acestuia, se pot instala un cluster Kafka pe Kubernetes cu doar câteva comenzi:.

Pentru a construi acest proiect de partea TravisCI, este necesar să configurezi variabilele de mediu

GH_REF — o valoare de forma github.com/inponomarev/csa-hb
GH_TOKEN — un token de acces la GitHub. Poate fi obținut în GitHub în setările profilului tău, Developer Settings -> Personal Access Tokens. Dacă publici prezentarea într-un repository public, pentru acest token este suficient să specifici un singur nivel de acces „Access public repositories”.
GH_USER_EMAIL / GH_USER_NAME — o pereche nume/email, din partea căreia va fi efectuat push-ul în ramură gh-pages.

Astfel, fiecare commit de cod al prezentării pe GitHub duce la recompilarea automată a diapozitivelor în formatele HTML și PDF și la reîncărcarea lor pe github.io. (Desigur, ar trebui să publici pe github.io doar acele prezentări pe care vrei în cele din urmă să le faci publice.)

Exemple de proiecte

În încheiere — linkuri către câteva exemple de proiecte de prezentare cu scripturi Maven configurate și configurații CI pentru Travis-CI, pe care le poți clona și utiliza la crearea propriilor proiecte de prezentare: