🥇Prezentacja jako kod, czyli dlaczego przestałem używać Powerpointa

W mojej karierze w IT miałem okazję przygotować dziesiątki prezentacji dla kolegów, klientów oraz na wystąpienia publiczne. Przez wiele lat PowerPoint był dla mnie naturalnym i niezawodnym wyborem jako narzędzie do tworzenia slajdów. Jednak w tym roku sytuacja uległa znaczącej zmianie. Od lutego do maja wystąpiłem na pięciu konferencjach, a slajdy do moich prezentacji musiały być przygotowywane w krótkim czasie, ale z zachowaniem wysokiej jakości. Pojawiła się kwestia delegowania części pracy związanej z wizualnym projektem slajdów innym osobom. Pewnego razu spróbowałem współpracować z projektantem, przesyłając pliki .pptx mailem, ale praca zamieniła się w chaos: nikt nie wiedział, która wersja slajdów jest 'najświeższa', a układ 'psuł się' z powodu różnic w wersjach PowerPointa i czcionkach na naszych komputerach. Postanowiłem spróbować czegoś nowego. Spróbowałem, i od tamtej pory nie myślę o powrocie do PowerPointa.

Czego oczekujemy

Około półtora roku temu w naszej firmie zrezygnowaliśmy z używania Worda do tworzenia dokumentacji projektowej, napotykając te same problemy: choć Word jest dobry do pisania małych dokumentów, wraz ze wzrostem objętości pojawiają się trudności ze współpracą oraz z uzyskaniem wysokiej jakości i jednolitego formatu. Postawiliśmy na AsciiDoctor, z czego jesteśmy bardzo zadowoleni, ale to temat na osobny artykuł. W tym samym czasie zdaliśmy sobie sprawę z efektywności jednej z zasad DevOps „wszystko jako kod”, więc wybór wymagań dla nowej technologii tworzenia prezentacji był dość oczywisty:

Prezentacja powinna być zwykłym plikiem tekstowym w języku znaczników.
Slajdy dotyczą projektów rozwojowych, dlatego znacznik musi umożliwiać łatwe, bez pomocy zewnętrznych systemów, wstawianie
- fragmentów kodu z podświetleniem składni,
- prosty diagram w formie figur geometrycznych połączonych strzałkami,
- diagramów UML, schematów blokowych i tym podobnych.
Projekt prezentacji powinien być przechowywany w systemie kontroli wersji.
Walidacja i budowa gotowych slajdów powinny odbywać się w systemie CI.

Obecnie istnieją dwa podstawowe warianty tworzenia slajdów w językach znaczników: pakiet beamer dla LaTeX-a lub jeden z frameworków do tworzenia slajdów w HTML/CSS (RevealJS, remark, deck.js i wiele innych).

Choć moja dusza skłania się ku LaTeX-owi, rozum podpowiadał, że wybór rozwiązania, które nie będzie używane wyłącznie przez mnie, powinien być po stronie rozwiązania znanego szerszemu gronu. LaTeX nie jest znany każdemu, a jeśli twoja codzienna praktyka nie związana jest z pisaniem artykułów naukowych, to mało prawdopodobne, że znajdziesz czas na zanurzenie się w ogromny, skomplikowany świat tego systemu.

Jednakże, znajomość HTML/CSS również nie jest powszechnie rozpowszechnioną umiejętnością: ja, na przykład, nie opanowałem jej w pełni. Na szczęście, pomocny jest już znany nam AsciiDoctor: konwerter asciidoctor-revealjs pozwala tworzyć slajdy RevealJS, korzystając z składni AsciiDoctor. A ta jest na tyle prosta do nauki, że dostępna dla każdego!

Jak zakodować slajdy

Aby zrozumieć istotę kodowania slajdów w AsciiDoctor, najłatwiej jest podać konkretne przykłady. Wszystkie pochodzą z rzeczywistych slajdów, które przygotowałem na moje konferencyjne wystąpienia w tym roku.

Slajd z nagłówkiem i listą otwierającą się punktami:

== Po co nam Streams API?

[%step]
* Przetwarzanie strumieni w czasie rzeczywistym
* API przypominające strumień (map / reduce)
* Pod maską:
** Automatyczne zatwierdzanie offsetu
** Przebudowa
** Wewnętrzny stan przetwarzaczy
** Łatwe skalowanie

Wynik

Nagłówek i fragment kodu źródłowego z podświetleniem składni:

== Kafka Streams API: ogólna struktura aplikacji KStreams

[source,java]
----
StreamsConfig config = ...;
// Tutaj ustalamy różne opcje

Topology topology = new StreamsBuilder()
// Tutaj budujemy topologię
....build();
----

Wynik

W trakcie przygotowań do wystąpienia przykłady kodu są wielokrotnie poprawiane i ulepszane, dlatego cenną możliwością jest szybkie skopiowanie i wklejenie „surowego kodu” bezpośrednio do slajdu, zapewniając aktualność przykładu demo i nie martwiąc się o podświetlenie składni.

Nagłówek, ilustracja i tekst (układ po slajdzie wykonujemy w komórkach tabeli AsciiDoctor):

== Kafka Streams w Akcji

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
"Kafka Streams w Akcji", listopad 2018
* Przykłady kodu dla Kafka 1.0
|===

Wynik

Czasami nagłówek nie jest potrzebny, a dla ilustracji twojej myśli potrzebny jest po prostu obrazek na cały ekran:

[%notitle]
== Życie wlegacy to niełatwe zadanie

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

Wynik

Często myśl należy wesprzeć prostą diagramem, w postaci „kwadratów połączonych strzałkami”. Na szczęście, AsciiDoctor jest zintegrowany z systemem Graphviz — językiem, który pozwala opisywać wykresy graficzne na podstawie opisu wierzchołków i połączeń między nimi. Graphviz trzeba opanować, ale na podstawie dostępnych przykładów jest to dość proste! Oto jak to wygląda:

== Pisanie „Aplikacji do Sumowania Zakładów”

Jaka jest suma wypłat z dokonanych zakładów, jeśli wynik okaże się korzystny?

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

Wynik

W przypadku, gdy konieczne jest edytowanie podpisu na figurze, zmiana kierunku strzałki itp. — można to zrobić bezpośrednio w kodzie prezentacji, zamiast przerysowywać gdzieś obrazek i ponownie wstawiać go do slajdu. To znacznie przyspiesza pracę nad slajdami.

Przykład bardziej złożony:

== Niemożliwa do Powtórzenia Kompilacja
[graphviz, "unstable-update.png"]
-----
digraph G {
  rankdir="LR";
  graph [ dpi = 150 ];
  u -> r0;
  u[shape=plaintext; label="linter updaten+ 13 warningów"]
  r0[shape=point, width = 0]
  r1 -> r0[ arrowhead = none, label="gałąź master" ];
  r0-> r2 [];   b1 -> b4;  r1->b1
  r1[label="150nwarningów"]
  b1[label="± 0nwarningów"]
  b4[label="± 0nwarningów"]
  b4->r2
  r2[label="163nwarningów", color="red", xlabel=<merge blocked>]
  {rank = same; u; r0; b4;}
}
-----

Wynik

Przy okazji, eksperymentowanie z Graphviz i debugowanie obrazków jest wygodne na stronie Graphviz online.

W końcu, jeśli trzeba wstawić do slajdu schemat blokowy, diagram klas lub inną znormalizowaną diagramę, może do pomocy przyjść jeszcze jeden zintegrowany z AsciiDoctor system, PlantUML. O obszernych możliwościach PlantUML mój kolega Nikolaj Potashnikov napisał osobny post.

Przekształcenie projektu prezentacji w kod przechowywany w systemie kontroli wersji daje możliwość zorganizowania wspólnej pracy nad prezentacją, przede wszystkim podziału zadań tworzenia treści i formatu. Formatowanie slajdów (czcionki, tła, odstępy) w RevealJS opisuje się za pomocą CSS. Moja osobista zdolność do radzenia sobie z CSS najlepiej przedstawia ta gifka — ale to nie jest straszne, gdy są ludzie, którzy pracują z CSS znacznie sprawniej i szybciej niż ja. W efekcie, gdy zbliża się termin prezentacji, możemy jednocześnie pracować nad różnymi plikami przez Git i zwiększać szybkość wspólnej pracy, niemożliwą podczas przesyłania plików .pptx mailem.

Zbieranie strony HTML z slajdami

Proste źródła są świetne, ale jak skompilować je w prezentację?

AsciiDoctor to projekt napisany w Ruby, który można uruchomić na kilka sposobów. Po pierwsze, możesz zainstalować język Ruby i uruchomić asciidoctor bezpośrednio, co prawdopodobnie będzie najbliższe deweloperom Ruby.

Jeśli nie chcesz zajmować się instalacją Ruby, możesz skorzystać z obrazu dockerowego asciidoctor/docker-asciidoctor, który po uruchomieniu pozwala zamontować folder z kodami źródłowymi projektu przez VOLUME i uzyskać wynik w określonym miejscu.

Opcja, na której się skupiłem, może wydawać się nieco zaskakująca, ale jest dla mnie najwygodniejsza jako dewelopera Java. Nie wymaga ani instalacji Ruby, ani posiadania dockera, a pozwala generować slajdy za pomocą skryptu Maven.

Rzecz w tym, że projekt JRuby — implementacja języka Ruby w Javie — jest na tyle dobra, że pozwala uruchomić praktycznie wszystko, co stworzono dla Ruby na maszynie Java, a uruchomienie AsciiDoctora to jedno z najczęstszych stosowań JRuby.

Obecność asciidoctor-maven-plugin pozwala zbierać dokumentację AsciiDoctor, będącą częścią projektu Java (z czego aktywnie korzystamy). W tym przypadku AsciiDoctor i JRuby są automatycznie pobierane przez Maven, a AsciiDoctor działa w środowisku JRuby: nic nie trzeba instalować na maszynie! (Z wyjątkiem pakietu graphviz, który jest potrzebny, jeśli chcesz używać grafiki GraphViz lub PlantUML.) Wystarczy umieścić swoje pliki .adoc w folderze src/main/asciidoc/. Oto przykład pomnika, który generuje slajdy z diagramami.

Konwersja slajdów do PDF

Chociaż wersja HTML slajdów jest całkowicie samodzielna, czasami potrzebna jest również wersja PDF slajdów. Po pierwsze, zdarza się, że na niektórych konferencjach, które nie zapewniają prelegentowi możliwości podłączenia własnego laptopa, wymagają slajdów 'ściśle w formacie pptx lub pdf', nie spodziewając się, że istnieją także w HTML. Po drugie, dobrym zwyczajem jest wysłanie organizatorom niezmiennej wersji swoich slajdów w takim formacie, w jakim były one pokazane podczas prezentacji, w formacie PDF do publikacji pliku w materiałach konferencyjnych.

Na szczęście, z tym zadaniem radzi sobie narzędzie Node.js decktape, oparte na Puppeteer — systemie automatyzacji zarządzania przeglądarką Chrome. Slajdy RevealJS można przekonwertować do PDF za pomocą polecenia

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

Dwa triki przy uruchamianiu decktape, do których doszedłem metodą prób i błędów:

rozszerzenie przez parametr -s należy ustawić z dwuipółkrotnym zapasem, w przeciwnym razie mogą wystąpić problemy z wynikami konwersji
w URL wersji HTML prezentacji należy przekazać parametr ?fragments=true, co pozwoli na tworzenie osobnej strony PDF dla każdego pośredniego stanu slajdu (na przykład pięć stron dla pięciu punktów listy, jeśli są pokazywane jeden po drugim). To pozwoli na wykorzystanie takiego PDF jako prezentacji podczas wystąpienia.

Automatyczna kompilacja i publikacja w sieci

Wygodne jest, gdy slajdy są automatycznie zbierane po wprowadzeniu zmian w systemie kontroli wersji, a jeszcze wygodniej, gdy automatycznie skompilowane slajdy są publikowane w Internecie do ogólnego użytku. Slajdy z Internetu można łatwo 'przegrać' przed publicznością z dowolnej maszyny połączonej z internetem i projektorem.

Ponieważ używamy w pracy GitHub, naturalnym wyborem systemu CI jest TravisCI, a do hostingu gotowych prezentacji — github.io. Idea github.io polega na tym, że wszelka statyczna zawartość umieszczona w gałęzi gh-pages twojego projektu na GitHub staje się dostępna pod adresem .github.io/.

Pełny plik konfiguracyjny TravisCI, zawierający kompilację HTML wersji strony przy użyciu Mavena, konwersję do PDF za pomocą decktape i przesłanie wyników do gałęzi gh-pages do publikacji na github.io, wygląda tak.

Aby zbudować taki projekt po stronie TravisCI, musisz skonfigurować zmienne środowiskowe

GH_REF — wartość w formacie github.com/inponomarev/csa-hb
GH_TOKEN — token dostępu do GitHub. Można go uzyskać w GitHub w ustawieniach swojego profilu, Developer Settings -> Personal Access Tokens. Jeśli publikujesz prezentację w publicznym repozytorium, to dla tego tokenu wystarczy wskazać jeden poziom dostępu "Access public repositories".
GH_USER_EMAIL / GH_USER_NAME — para imię/adres e-mail, w imieniu której będzie realizowane przesyłanie do gałęzi gh-pages.

W ten sposób każdy commit kodu prezentacji na GitHub prowadzi do automatycznego przetworzenia slajdów w formatach HTML i PDF oraz ich ponownego przesłania na github.io. (Oczywiście publikować na github.io należy tylko te prezentacje, które chcesz ostatecznie uczynić publicznymi.)

Przykłady projektów

Na koniec — linki do kilku przykładów projektów prezentacji z skonfigurowanymi skryptami Maven i konfiguracją CI dla Travis-CI, które można sklonować i wykorzystać podczas tworzenia własnych projektów prezentacji: