Predstavitev kot koda ali Zakaj ne uporabljam več Powerpointa

Mislim, da sem v svoji IT karieri izvedel na desetine predstavitev kolegom, strankam in javno nastopil. Dolga leta je bil Powerpoint zame naravna in zanesljiva izbira kot orodje za izdelavo diapozitivov. Toda letos so se razmere kvalitativno spremenile. Od februarja do maja sem imel priložnost govoriti na petih konferencah, prosojnice za poročila pa je bilo treba pripraviti v kratkem času, a kakovostno. Pojavilo se je vprašanje, kako del dela glede vizualnega oblikovanja diapozitivov prenesti na druge osebe. Nekoč sem poskušal sodelovati z oblikovalcem in pošiljal datoteke .pptx po pošti, vendar se je delo spremenilo v kaos: nihče ni vedel, katera različica diapozitivov je »najnovejša«, postavitev pa se je »premikala« zaradi razlike v Powerpointu. različice in pisave na naših napravah. In sem se odločil poskusiti nekaj novega. Poskusil sem in od takrat nisem več pomislil, da bi se vrnil k Powerpointu.

Kaj hočemo

Pred približno letom in pol je naše podjetje prenehalo uporabljati Word za izdelavo projektne dokumentacije, saj smo naleteli na enake težave: čeprav je Word dober za tipkanje majhnega dokumenta, se z večanjem obsega pojavljajo težave pri sodelovanju in pridobivanju kakovostnih in enotno oblikovanje. Naša izbira je padla na AsciiDoctor, in nikoli se ne prenehamo veseliti te izbire, vendar je to tema za ločen članek. Približno v istem času smo se naučili učinkovitosti enega od načel DevOps »vse kot koda«, zato je bila izbira zahtev za novo tehnologijo za ustvarjanje predstavitvenih diapozitivov povsem očitna:

1. Predstavitev mora biti datoteka z navadnim besedilom v označevalnem jeziku.
2. Naši diapozitivi se nanašajo na razvojne projekte, zato mora biti oznaka preprosta za vstavljanje, brez uporabe zunanjih sistemov
   • fragmenti kode z označevanjem sintakse,
   • preprosti diagrami v obliki geometrijskih oblik, povezanih s puščicami,
   • Diagrami UML, diagrami poteka in drugo.
3. Osnutek predstavitve mora biti shranjen v sistemu za nadzor različic.
4. Validacijo in sestavljanje končnih diapozitivov je treba izvesti v sistemu CI.

Danes obstajata dve osnovni možnosti za ustvarjanje diapozitivov v označevalnih jezikih: paket beamer za LaTeX ali eno od ogrodij za ustvarjanje diapozitivov z uporabo HTML/CSS (Razkrij JS, pripombe, deck.js in mnogi drugi).

Čeprav mi leži duša v LaTeXu, mi je razum narekoval, da je izbira rešitve, ki je ne bom edini uporabljal, na strani rešitve, ki jo pozna širši krog ljudi. LaTeXa ne poznajo vsi in če vaša dnevna praksa ni povezana s pisanjem znanstvenih člankov, potem verjetno ne boste imeli časa, da bi se potopili v ogromen, zapleten svet tega sistema.

Vendar obvladovanje HTML/CSS ni ravno razširjena veščina: jaz ga na primer še zdaleč ne obvladam v celoti. Na srečo priskoči na pomoč že znani AsciiDoctor: pretvornik asciidoctor-revealjs omogoča ustvarjanje diapozitivov RevealJS z uporabo oznake AsciiDoctor. Poleg tega je enostaven za učenje in dostopen vsem!

Kako kodirati diapozitive

Da bi razumeli bistvo kodiranja diapozitivov na AsciiDoctor, je najlažji način, da navedete konkretne primere. Vse to je iz dejanskih diapozitivov, ki sem jih naredil za svoje letošnje konferenčne predstavitve.

Diapozitiv z naslovom in seznamom v elementih, ki se odpirajo drug za drugim:

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

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

Rezultat

Glava in delček izvorne kode z označevanjem sintakse:

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

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

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

Rezultat

V pripravah na govor so predstavitve kode podvržene ponavljajočim se revizijam in izboljšavam, zato je možnost hitrega kopiranja in lepljenja »surove kode« neposredno v prosojnico neprecenljiva, kar zagotavlja, da je predstavitev posodobljena brez skrbi glede označevanja sintakse.

Naslov, ilustracija in besedilo (postavitev na prosojnici je v celicah AsciiDoctor tabele):

== Kafka Streams in Action

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

Rezultat

Včasih naslov ni potreben in za ponazoritev vaše točke potrebujete samo celozaslonsko sliko:

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

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

Rezultat

Pogosto je treba idejo podpreti s preprostim diagramom v obliki »kvadratov, povezanih s puščicami«. Na srečo je AsciiDoctor integriran s sistemom Graphviz — jezik, ki omogoča opisovanje diagramov grafov na podlagi opisa vozlišč in povezav med njimi. Graphviz zahteva krivuljo učenja, vendar je glede na podane primere precej enostavno! Takole izgleda:

== Пишем “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;}
}
-----

Rezultat

V primeru, ko je treba urediti napis na sliki, spremeniti smer puščice ipd., lahko to storite neposredno v predstavitveni kodi, namesto da bi sliko nekje prerisali in jo znova vstavili v diapozitiv. To bistveno poveča hitrost dela na diapozitivih.

Bolj zapleten primer:

== Невоспроизводимая сборка
[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;}
}
-----

Rezultat

Mimogrede, priročno je eksperimentirati z Graphvizom in odpravljati napake v slikah na strani Graphviz na spletu.

Nazadnje, če morate v prosojnico vstaviti diagram poteka, diagram razredov ali drug standardiziran diagram, vam lahko na pomoč priskoči drug sistem, integriran z AsciiDoctor, PlantUML. Moj kolega Nikolaj Potašnikov je pisal o obsežnih zmožnostih PlantUML ločena objava.

Pretvorba predstavitvenega projekta v kodo, shranjeno v sistemu za nadzor različic, omogoča organizacijo skupnega dela na predstavitvi, najprej ločitev nalog ustvarjanja vsebine in oblikovanja. Oblikovanje diapozitivov (pisave, ozadja, zamiki) v RevealJS je opisano s pomočjo CSS. Moje osebno znanje s CSS najbolje izraža ta gif - vendar ni strašno, ko obstajajo ljudje, ki delajo s CSS veliko bolj spretno in hitreje kot jaz. Posledično se izkaže, da lahko ob hitro bližajočem se roku za predstavitev prek Gita delamo na različnih datotekah hkrati in razvijemo hitrost sodelovanja, ki je nemogoča pri pošiljanju datotek .pptx po pošti.

Izdelava strani HTML z diapozitivi

Viri navadnega besedila so odlični, toda kako jih združiti v samo predstavitev?

AsciiDoctor je projekt, napisan v Rubyju, in obstaja več načinov za njegovo izvajanje. Prvič, lahko namestite jezik Ruby in neposredno zaženete asciidoctor, kar je verjetno najbližje razvijalcem Rubyja.

Če se ne želite zapletati z nameščanjem Rubyja, lahko uporabite sliko dockerja asciidoctor/docker-asciidoctor, v katerega lahko ob zagonu preko VOLUME povežete mapo z viri projekta in dobite rezultat na danem mestu.

Možnost, ki sem jo izbral, se morda zdi nekoliko nepričakovana, vendar je zame kot razvijalca Java najprimernejša. Ne zahteva namestitve Rubyja ali dockerja, vendar vam omogoča ustvarjanje diapozitivov s skriptom Maven.

Bistvo je, da projekt JRuby - Izvedba jezika Ruby v Javi je tako dobra, da omogoča zagon skoraj vsega, kar je ustvarjeno za Ruby, v stroju Java, zagon AsciiDoctorja pa je ena najpogostejših uporab JRuby.

razpoložljivost asciidoctor-maven-plugin omogoča zbiranje dokumentacije AsciiDoctor, ki je del Java projekta (ki ga aktivno uporabljamo). Istočasno Maven samodejno prenese AsciiDoctor in JRuby, AsciiDoctor pa deluje v okolju JRuby: na stroj ni treba ničesar namestiti! (Brez paketa graphviz, ki je potreben, če želite uporabljati grafiko GraphViz ali PlantUML.) Datoteke .adoc preprosto postavite v mapo src/main/asciidoc/. Tukaj primer pomnikazbiranje prosojnic z diagrami.

Pretvorite diapozitive v PDF

Čeprav je HTML različica diapozitivov precej samozadostna, je vseeno treba imeti PDF različico diapozitivov. Prvič, zgodi se, da na nekaterih konferencah, ki govorcu ne omogočajo povezave z lastnim prenosnikom, zahtevajo diapozitive »strogo v formatu pptx ali pdf«, ne da bi pričakovali, da so tudi v HTML. Drugič, dobro je, da organizatorjem pošljete nelektorirano različico svojih diapozitivov, kot so bili prikazani na poročilu, v formatu PDF za objavo datoteke v gradivu konference.

Na srečo pripomoček Node.js obravnava to nalogo. decktape, zgrajen na podlagi Lutkar — sistemi avtomatizacije za upravljanje brskalnika Chrome. Predstavitev RevealJS lahko pretvorite v PDF z ukazom

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

Dva trika pri zagonu decktape-a, do katerih smo morali priti s poskusi in napakami:

• ločljivost preko parametra -s je treba določiti z dvakratnim robom, sicer lahko pride do težav z rezultati pretvorbe

• v URL-ju različice HTML predstavitve morate posredovati parameter ?fragments=true, ki bo ustvaril ločeno stran PDF za vsako vmesno stanje vašega diapozitiva (na primer pet strani za pet točk, če so prikazane ena za drugo). To vam bo omogočilo, da uporabite tak PDF samostojno kot predstavitev med poročilom.

Samodejno sestavljanje in objava na spletu

Priročno je, če se diapozitivi samodejno prevedejo, ko se spremeni sistem za nadzor različic, in še bolj priročno, ko se samodejno prevedeni diapozitivi objavijo na internetu za javno uporabo. Diapozitive iz interneta je mogoče enostavno "predvajati" pred občinstvom s katerega koli računalnika, povezanega z internetom, in projektorja.

Ker pri svojem delu uporabljamo GitHub, je naravna izbira CI sistem TravisCI, in za gostovanje že pripravljenih predstavitev - github.io. Ideja za github.io je, da se vsaka statična vsebina objavi v veji gh-pages vašega projekta na GitHubu, postane na voljo na <ваше имя>.gihub.io/<ваш проект>.

Celotna konfiguracijska datoteka TravisCI, vključno s prevajanjem HTML različice strani z Mavenom, pretvorbo v PDF z decktape in nalaganjem rezultatov v nit gh-pages za objavo na github.io, izgleda Tako.

Če želite zgraditi tak projekt na strani TravisCI, morate konfigurirati spremenljivke okolja

• GH_REF — vrednost, kot je github.com/inponomarev/csa-hb
• GH_TOKEN — Žeton za dostop GitHub. Dobite ga lahko na GitHubu v nastavitvah profila, Nastavitve razvijalca -> Žetoni osebnega dostopa. Če naložite predstavitev v javno skladišče, je za ta žeton dovolj, da določite edino raven dostopa »Dostop do javnih skladišč«.
• GH_USER_EMAIL / GH_USER_NAME — par ime/e-pošta, v imenu katerega bo izvedeno potiskanje v nit gh-pages.

Tako vsaka potrditev predstavitvene kode na GitHub povzroči, da se diapozitivi samodejno znova zgradijo v formatih HTML in PDF ter ponovno naložijo na github.io. (Seveda bi morali na github.io naložiti samo tiste predstavitve, ki jih končno želite objaviti.)

Primeri projektov

Nazadnje je tukaj povezav do nekaj primerov predstavitvenih projektov s prilagojenimi skripti Maven in konfiguracijo CI za Travis-CI, ki jih je mogoče klonirati in uporabiti pri ustvarjanju lastnih predstavitvenih projektov:

• https://github.com/inponomarev/kstreams-examples (moj govor za JPoint 2019)

• https://github.com/inponomarev/csa-hb (moje poročilo za Heisenbug 2019)

Adijo Powerpoint! Mislim, da te ne bom nikoli potreboval za tehnične predstavitve :)

Vir: www.habr.com