🥇 Präsentation als Code, oder Warum ich PowerPoint nicht mehr benutze

In meiner IT-Karriere hatte ich die Gelegenheit, dutzende Präsentationen für Kollegen, Kunden und öffentliche Auftritte zu halten. Viele Jahre lang war PowerPoint für mich das natürliche und zuverlässige Werkzeug zur Erstellung von Folien. Doch in diesem Jahr hat sich die Situation grundlegend geändert. Von Februar bis Mai durfte ich auf fünf Konferenzen sprechen, wobei die Folien für die Vorträge in kurzer Zeit, aber qualitativ hochwertig erstellt werden mussten. Daher stellte sich die Frage, den visuellen Designteil der Folien an andere Personen zu delegieren. Einmal versuchte ich, mit einem Designer zusammenzuarbeiten, indem ich .pptx-Dateien per E-Mail verschickte, aber es wurde chaotisch: Niemand wusste, welche Version der Folien die „neueste“ war, und das Layout variierte aufgrund unterschiedlicher PowerPoint-Versionen und Schriftarten auf unseren Maschinen. Also beschloss ich, etwas Neues auszuprobieren. Ich versuchte es und seitdem denke ich nicht mehr daran, zu PowerPoint zurückzukehren.

Was wir möchten

Vor etwa anderthalb Jahren haben wir in unserem Unternehmen beschlossen, auf Word für die Erstellung von Projektdokumentationen zu verzichten. Wir hatten mit genau denselben Problemen zu kämpfen: Während Word für kleinere Dokumente geeignet ist, bringt die zunehmende Dokumentationsmenge Schwierigkeiten bei der Zusammenarbeit und dem Erhalt einer qualitativ hochwertigen, einheitlichen Formatierung mit sich. Unsere Wahl fiel auf AsciiDoctor, und darüber freuen wir uns immer noch, aber das ist ein Thema für einen separaten Artikel. Etwa zu dieser Zeit erkannten wir die Effizienz eines der DevOps-Prinzipien „everything as code“, was unsere Anforderungen an die neue Technologie zur Erstellung von Präsentationsfolien ziemlich offensichtlich machte:

Eine Präsentation sollte aus einer plain text-Datei im Markup-Format bestehen.
Unsere Folien beziehen sich auf Entwicklungsprojekte, daher sollte das Markup es ermöglichen, einfach und ohne Hilfe externer Systeme
- Code-Snippets mit Syntax-Hervorhebung einzufügen,
- einfache Diagramme in Form von geometrischen Figuren, die durch Pfeile verbunden sind,
- UML-Diagramme, Flussdiagramme und mehr.
Das Projekt der Präsentation sollte im Versionskontrollsystem gespeichert werden.
Die Validierung und Kompilierung der fertigen Folien sollte in der CI-Plattform erfolgen.

Für heute gibt es zwei grundlegende Möglichkeiten, Folien in Markup-Sprachen zu erstellen: das Paket beamer für LaTeX oder eines der Frameworks zur Erstellung von Folien in HTML/CSS (RevealJS, remark, deck.js und viele andere).

Obwohl mein Herz für LaTeX schlägt, hat mein Verstand mir gesagt, dass ich eine Lösung wählen sollte, die nicht nur ich benutze, sondern die auch einem breiteren Publikum bekannt ist. LaTeX ist nicht jedermanns Sache, und wenn Ihre tägliche Arbeit nicht mit dem Schreiben von wissenschaftlichen Artikeln verbunden ist, werden Sie wahrscheinlich nicht die Zeit haben, sich in die komplexe Welt dieses Systems einzuarbeiten.

Allerdings ist auch das Wissen über HTML/CSS kein verbreiteter Skill: Ich beispielsweise beherrsche es bei weitem nicht in vollem Umfang. Zum Glück kommt uns hier der bereits bekannte AsciiDoctor zur Hilfe: Der Konverter asciidoctor-revealjs ermöglicht die Erstellung von RevealJS-Folien mit AsciiDoctor-Markup. Und dieses ist einfach zu erlernen und für jeden zugänglich!

Wie man Folien codiert

Um die Grundlagen der Foliencodierung in AsciiDoctor zu verstehen, ist es am einfachsten, konkrete Beispiele zu geben. Alle stammen aus realen Folien, die ich in diesem Jahr für meine Konferenzvorträge erstellt habe.

Titel-Slide mit einer Liste von Punkten, die nacheinander ausgeklappt werden:

== Warum benötigen wir das Streams API?

[%step]
* Echtzeit-Stream-Verarbeitung
* Stream-ähnliche API (map / reduce)
* Im Hintergrund:
** Automatisches Offset-Commit
** Rebalancing
** Internen Zustand der Handler
** Einfaches Scaling

Ergebnis

Titel und ein Code-Snippet mit Syntax-Highlighting:

== Kafka Streams API: Grundstruktur einer KStreams-Anwendung

[source,java]
----
StreamsConfig config = ...;
// Hier setzen wir verschiedene Optionen

Topology topology = new StreamsBuilder()
// Hier bauen wir die Topologie
....build();
----

Ergebnis

Im Zuge der Vorbereitung des Vortrags werden die Beispielcodes mehrfach überarbeitet und optimiert. Daher ist es wertvoll, die Möglichkeit zu haben, den „rohen Code“ schnell zu kopieren und direkt in die Folie einzufügen, um die Aktualität des Demo-Beispiels sicherzustellen, ohne sich um die Syntax-Hervorhebung kümmern zu müssen.

Titel, Illustrierung und Text (die Anordnung auf der Folie erfolgt in den Zellen der AsciiDoctor-Tabelle):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
„Kafka Streams in Action“, November 2018
* Beispielcodes für Kafka 1.0
|===

Ergebnis

Manchmal ist kein Titel erforderlich, und um deine Idee zu verdeutlichen, genügt einfach ein Bild über die gesamte Folie:

[%notitle]
== Leben in Legacy ist nicht einfach

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

Ergebnis

Oft ist es nötig, eine Idee mit einem einfachen Diagramm zu untermauern, das aus „Kästen, die mit Pfeilen verbunden sind“ besteht. Glücklicherweise ist AsciiDoctor in das System integriert, Graphviz — eine Sprache, die es ermöglicht, Diagramme zu beschreiben, die auf der Beschreibung von Knoten und den Verbindungen zwischen ihnen basieren. Graphviz muss man lernen, aber basierend auf den vorhandenen Beispielen ist das ziemlich einfach! So sieht es aus:

== Schreiben der „Bet Totalling App“

Was ist die Auszahlungssumme für getätigte Einsätze, wenn das Ergebnis eintritt?

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

Ergebnis

Falls es nötig ist, die Beschriftung in der Figur zu bearbeiten, die Richtung des Pfeils zu ändern usw. — kann dies direkt im Präsentationscode durchgeführt werden, anstatt ein Bild irgendwo neu zu zeichnen und es erneut in die Folie einzufügen. Das erhöht die Effizienz bei der Arbeit an Folien erheblich.

Ein komplexeres Beispiel:

== Nicht reproduzierbare Zusammenstellung
[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;}
}
-----

Ergebnis

Übrigens ist es praktisch, mit Graphviz zu experimentieren und Bilder auf der Seite zu debuggen. Graphviz online.

Wenn Sie schließlich ein Flussdiagramm, ein Klassendiagramm oder ein anderes standardisiertes Diagramm in eine Folie einfügen müssen, kann ein weiteres, in AsciiDoctor integriertes System helfen, PlantUML. Mein Kollege Nikolai Potashnikov hat einen separaten Beitrag.

die gesamte Präsentation in Code zu verwandeln, der im Versionskontrollsystem gespeichert ist, ermöglicht eine Zusammenarbeit an der Präsentation, insbesondere die Aufgaben zur Erstellung von Inhalten und zum Design zu trennen. Das Design der Folien (Schriftarten, Hintergründe, Abstände) in RevealJS wird mithilfe von CSS beschrieben. Meine persönliche Fähigkeit, mit CSS umzugehen, wird am besten durch diese GIF gezeigt. — aber das ist nicht schlimm, wenn es Leute gibt, die viel geschickter und schneller mit CSS arbeiten als ich. So können wir, angesichts der schnell näher kommenden Deadline für die Präsentation, gleichzeitig an verschiedenen Dateien über Git arbeiten und die Geschwindigkeit der Zusammenarbeit entwickeln, die mit dem Versenden von .pptx-Dateien per E-Mail unmöglich wäre.

Zusammenstellung einer HTML-Seite mit Folien

Reiner Text-Quellcode ist großartig, aber wie kompiliert man ihn zur eigentlichen Präsentation?

AsciiDoctor ist ein in Ruby geschriebenes Projekt, das auf mehrere Arten gestartet werden kann. Erstens können Sie die Programmiersprache Ruby installieren und asciidoctor direkt ausführen, was wahrscheinlich für Ruby-Entwickler am nahegelegensten ist.

Wenn Sie sich nicht mit der Installation von Ruby herumschlagen möchten, können Sie das Docker-Image verwenden asciidoctor/docker-asciidoctor, das beim Starten Ihnen ermöglicht, über VOLUME einen Ordner mit den Projektquellen anzuschließen und das Ergebnis an einem bestimmten Ort zu erhalten.

Die Variante, auf der ich gelandet bin, mag etwas unerwartet erscheinen, ist aber für mich als Java-Entwickler am bequemsten. Es erfordert keine Ruby-Installation und kein Docker, ermöglicht aber die Generierung von Folien mit Hilfe eines Maven-Skripts.

Es geht darum, dass das Projekt JRuby — eine Java-Implementierung der Ruby-Sprache — so gut ist, dass es ermöglicht, nahezu alles, was für Ruby geschaffen wurde, in der Java-Maschine auszuführen, wobei die Ausführung von AsciiDoctor eine der häufigsten Anwendungen von JRuby ist.

Vorhandensein von asciidoctor-maven-plugin ermöglicht das Erstellen von AsciiDoctor-Dokumentationen, die Teil eines Java-Projekts sind (was wir aktiv nutzen). Dabei werden AsciiDoctor und JRuby automatisch von Maven heruntergeladen, und AsciiDoctor wird in der JRuby-Umgebung ausgeführt: es ist nichts auf der Maschine zu installieren! (Außer dem Paket graphviz, das benötigt wird, wenn Sie Grafiken von GraphViz oder PlantUML verwenden möchten.) Es genügt, Ihre .adoc-Dateien in den Ordner src/main/asciidoc/. Hier ist ein Beispiel für ein Denkmal, das Folien mit Diagrammen generiert.

Die Konvertierung von Folien in PDF

Obwohl die HTML-Version der Folien völlig eigenständig ist, kann es dennoch notwendig sein, auch eine PDF-Version der Folien zu haben. Erstens kommt es vor, dass auf einigen Konferenzen, die dem Redner nicht die Möglichkeit bieten, einen eigenen Laptop anzuschließen, die Folien "ausschließlich im pptx- oder pdf-Format" verlangen, ohne zu erwarten, dass sie auch in HTML vorliegen. Zweitens ist es gute Umgangsform, den Organisatoren eine unveränderliche Version Ihrer Folien in dem Format zuzusenden, wie sie während des Vortrags präsentiert wurden, im PDF-Format zur Veröffentlichung in den Konferenzmaterialien.

Glücklicherweise wird diese Aufgabe von einem Node.js-Tool decktape, das auf Puppeteer basiert – einem Automatisierungssystem für die Steuerung des Chrome-Browsers. Um eine RevealJS-Präsentation in PDF umzuwandeln, kann der folgende Befehl verwendet werden:

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

Zwei Tricks beim Ausführen von decktape, die ich durch Ausprobieren herausgefunden habe:

die Auflösung über den Parameter -s muss doppelt so hoch festgelegt werden, da sonst Probleme mit den Konvertergebnissen auftreten können.
im URL der HTML-Version der Präsentation muss der Parameter übergeben werden. ?fragments=true, was es ermöglicht, für jeden Zwischenzustand Ihrer Folie eine separate PDF-Seite zu erstellen (zum Beispiel fünf Seiten für fünf Punkte, wenn diese nacheinander gezeigt werden). Dadurch kann diese PDF auch eigenständig als Präsentation verwendet werden.

Automatische Zusammenstellung und Veröffentlichung im Web

Es ist praktisch, wenn Folien automatisch erstellt werden, wenn Änderungen im Versionskontrollsystem vorgenommen werden, und noch besser, wenn die automatisch kompilierten Folien im Internet für die allgemeine Nutzung veröffentlicht werden. Folien aus dem Internet können leicht von jedem mit dem Internet und einem Projektor verbundenen Gerät präsentiert werden.

Da wir in unserer Arbeit GitHub verwenden, ist die naheliegendste Wahl für das CI-System TravisCI, und für das Hosting der fertigen Präsentationen — github.io. Die Idee von github.io ist, dass jeder statische Inhalt, der in den Branch gh-pages Ihres Projekts auf GitHub platziert wird, unter der Adresse .github.io/.

Die vollständige Konfigurationsdatei für TravisCI, die die Kompilierung der HTML-Version der Seite mit Maven, die Konvertierung in PDF mittels DeckTape und das Hochladen der Ergebnisse in den Branch umfasst, gh-pages sieht folgendermaßen aus: so.

Um ein solches Projekt auf der TravisCI-Seite zu bauen, müssen Umgebungsvariablen eingerichtet werden:

GH_REF — ein Wert im Format github.com/inponomarev/csa-hb
GH_TOKEN — ein Zugangstoken für GitHub. Dieses kann in den Einstellungen Ihres GitHub-Profils unter Developer Settings -> Personal Access Tokens generiert werden. Wenn Sie eine Präsentation in einem öffentlichen Repository veröffentlichen, benötigen Sie für dieses Token nur den Zugriffslevel "Access public repositories."
GH_USER_EMAIL / GH_USER_NAME — ein Paar von Name/E-Mail, unter dem der Push in den Branch erfolgt. gh-pages.

Somit führt jeder Code-Commit der Präsentation auf GitHub zur automatischen Neuanordnung der Folien in HTML- und PDF-Formaten und deren erneuten Hochladen auf github.io. (Selbstverständlich sollten nur die Präsentationen auf github.io veröffentlicht werden, die Sie letztendlich öffentlich machen möchten.)

Beispiele für Projekte

Abschließend finden Sie Links zu einigen Beispielen von Präsentationsprojekten mit eingerichteten Maven-Skripten und CI-Konfigurationen für Travis-CI, die Sie klonen und für Ihre eigenen Präsentationsprojekte verwenden können: