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

Es scheint, ich habe in meiner Karriere in der IT Dutzende von Präsentationen für Kollegen, Auftraggeber und öffentliche Vorträge gehalten. Viele Jahre lang war PowerPoint als Tool zur Erstellung von Folien für mich die natürliche und zuverlässige Wahl. Doch in diesem Jahr hat sich die Situation grundlegend verändert. Von Februar bis Mai durfte ich auf fünf Konferenzen sprechen, und die Folien für die Vorträge mussten in kurzer Zeit, aber qualitativ hochwertig erstellt werden. Es stellte sich die Frage, einen Teil der Arbeit, der das visuelle Design der Folien betrifft, an andere Personen zu delegieren. Einmal versuchte ich, mit einem Designer zusammenzuarbeiten, indem ich .pptx-Dateien per E-Mail verschickte, aber die Arbeit verwandelte sich in ein Chaos: Niemand wusste, welche Version der Folien die 'neueste' war, und das Layout war aufgrund von Unterschieden in den Versionen von PowerPoint und den Schriftarten auf unseren Maschinen durcheinander geraten. Also beschloss ich, etwas Neues auszuprobieren. Ich habe es ausprobiert und seitdem denke ich nicht daran, zu PowerPoint zurückzukehren.

Was wir wollen

Vor etwa anderthalb Jahren haben wir in der Firma beschlossen, Word nicht mehr für die Erstellung von Projektdokumentationen zu verwenden, da wir auf dieselben Probleme gestoßen sind: Obwohl Word gut für die Erstellung kleiner Dokumente geeignet ist, treten mit wachsendem Umfang Schwierigkeiten bei der Zusammenarbeit und der Erreichung einer qualitativ hochwertigen und einheitlichen Formatierung auf. Unsere Wahl fiel auf AsciiDoctor, und über diese Entscheidung freuen wir uns weiterhin, aber das ist ein Thema für einen eigenen Artikel. Etwa zu dieser Zeit erkannten wir die Effizienz eines der DevOps-Prinzipien 'everything as code', daher war die Wahl der Anforderungen für die neue Technologie zur Erstellung von Präsentationsfolien ziemlich offensichtlich:

Eine Präsentation sollte aus einer Plain-Text-Datei in einer Markup-Sprache bestehen.
Die Folien befassen sich mit Entwicklungsprojekten, daher sollte die Markup-Sprache es ermöglichen, leicht, ohne die Hilfe externer Systeme, einzufügen
- Codeausschnitte mit Syntax-Highlighting,
- 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 der Zusammenbau der fertigen Folien sollten in einem CI-System erfolgen.

Heutzutage gibt es zwei grundlegende Varianten zur Erstellung von Folien in Markup-Sprachen: 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 meine Seele zu LaTeX neigt, hat der Verstand mir geraten, dass die Wahl einer Lösung, die nicht nur ich nutze, auf der Seite einer Lösung liegen sollte, die einem breiteren Publikum bekannt ist. LaTeX ist nicht jedem bekannt, und wenn Ihre tägliche Praxis nicht mit dem Schreiben wissenschaftlicher Arbeiten verbunden ist, werden Sie wahrscheinlich nicht die Zeit finden, in die riesige, komplexe Welt dieses Systems einzutauchen.

Allerdings ist auch das Beherrschen von HTML/CSS nicht gerade eine allgegenwärtige Fähigkeit: Ich selbst beherrsche es beispielsweise keineswegs vollständig. Glücklicherweise kommt hier unser bereits bekanntes AsciiDoctor zur Hilfe: ein Konverter asciidoctor-revealjs er ermöglicht das Erstellen von RevealJS-Slides unter Verwendung von AsciiDoctor-Markup. Und das ist einfach zu erlernen und für jeden zugänglich!

Wie man Slides codiert

Um das Wesen der Slide-Codierung mit AsciiDoctor zu verstehen, ist es am einfachsten, konkrete Beispiele zu bringen. Alle stammen von realen Slides, die ich für meine Konferenzvorträge in diesem Jahr erstellt habe.

Eine Folie mit einem Titel und einer Liste, bei der die Punkte nacheinander aufklappen:

== Warum benötigen wir die Streams API?

[%step]
* Echtzeit-Stream-Verarbeitung
* Stream-ähnliche API (map / reduce)
* Unter der Haube:
** Automatischer Offset-Commit
** Rebalancing
** Interner Zustand der Prozessoren
** Einfaches Skalieren

Ergebnis

Titel und ein Quellcode-Ausschnitt mit Syntaxhervorhebung:

== Kafka Streams API: allgemeine Struktur einer KStreams-Anwendung

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

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

Ergebnis

Im Vorbereitungsprozess für den Vortrag werden die Beispielcodes mehrfach überarbeitet und verbessert, daher ist es unbezahlbar, die Möglichkeit zu haben, den "Rohcode" schnell in die Folie einzufügen, um die Relevanz des Demo-Beispiels sicherzustellen, ohne sich um die Syntaxhervorhebung kümmern zu müssen.

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

== Kafka Streams in Action

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

Ergebnis

Manchmal ist kein Titel erforderlich, und für die Veranschaulichung Ihrer Gedanken genügt einfach ein Bild im Vollbildformat:

[%notitle]
== Es ist nicht leicht, in Legacy zu leben

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

Ergebnis

Oft muss ein Gedanke durch ein einfaches Diagramm, dargestellt als „Quadrate, die mit Pfeilen verbunden sind“, untermauert werden. Glücklicherweise ist AsciiDoctor in das System integriert Graphviz — in einer Sprache, die es ermöglicht, Diagramme auf der Grundlage der Beschreibung von Knoten und den Verbindungen zwischen ihnen zu beschreiben. Man muss sich mit Graphviz vertrautmachen, aber es ist ziemlich einfach, dafür auf die vorhandenen Beispiele zurückzugreifen! So sieht das aus:

== Schreiben einer "Bet Totalling App"

Wie hoch ist die Summe der Auszahlungen für die platzierte Wette, 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

Wenn es notwendig ist, die Beschriftung auf der Figur zu bearbeiten, die Richtung des Pfeils zu ändern usw. — dann kann dies direkt im Präsentationscode erfolgen, anstatt irgendwo das Bild neu zu zeichnen und es erneut in die Folie einzufügen. Das erhöht die Effizienz bei der Arbeit an den 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-Update+ 13 Warnungen"]
  r0[shape=point, width = 0]
  r1 -> r0[ arrowhead = none, label="Hauptzweig" ];
  r0-> r2 [];   b1 -> b4;  r1->b1
  r1[label="150nWarnungen"]
  b1[label="± 0nWarnungen"]
  b4[label="± 0nWarnungen"]
  b4->r2
  r2[label="163nWarnungen", color="red", xlabel=<<font color="red">Merge blockiert<\/font>>]
  {rank = same; u; r0; b4;}
}
-----

Ergebnis

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

Schließlich, wenn man ein Flussdiagramm, ein Klassendiagramm oder ein anderes standardisiertes Diagramm in eine Folie einfügen muss, kann in diesem Fall ein weiteres in AsciiDoctor integriertes System hilfreich sein, PlantUML. Über die umfangreichen Möglichkeiten von PlantUML schrieb mein Kollege Nikolai Potashnikov separaten Beitrag.

Die Umwandlung des Präsentationsprojekts in Code, der im Versionskontrollsystem gespeichert ist, ermöglicht eine organisierte Zusammenarbeit an der Präsentation, insbesondere die Trennung von Inhalten und Gestaltung. Die Gestaltung der Folien (Schriftarten, Hintergründe, Abstände) in RevealJS wird mittels 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 im Angesicht der schnell näher rückenden Frist für die Präsentation gleichzeitig an verschiedenen Dateien über Git arbeiten und die Geschwindigkeit der Zusammenarbeit erhöhen, die beim Versenden von .pptx-Dateien per E-Mail unmöglich wäre.

Zusammenstellung der HTML-Seite mit Folien

Einfache Textquellen sind großartig, aber wie kompiliert man sie in die eigentliche Präsentation?

AsciiDoctor ist ein in Ruby geschriebenes Projekt, das auf verschiedene Arten gestartet werden kann. Zunächst können Sie die Ruby-Sprache installieren und asciidoctor direkt ausführen, was für Ruby-Entwickler wahrscheinlich am nächsten kommt.

Wenn Sie sich nicht mit der Installation von Ruby befassen möchten, können Sie das Docker-Image nutzen asciidoctor/docker-asciidoctor, das beim Starten den Ordner mit den Projektquellen über VOLUME anschließen kann und an dem festgelegten Ort das Ergebnis erhält.

Die Variante, für die ich mich entschieden habe, mag etwas unerwartet erscheinen, ist aber für mich als Java-Entwickler am bequemsten. Sie erfordert weder die Installation von Ruby noch die Verfügbarkeit von Docker, ermöglicht jedoch die Generierung von Folien mit einem Maven-Skript.

Das Projekt JRuby — eine Java-Implementierung der Ruby-Sprache — ist so gut, dass es ermöglicht, praktisch alles, was für Ruby erstellt wurde, in der Java-Maschine auszuführen, und das Starten von AsciiDoctor ist eine der häufigsten Anwendungen von JRuby.

Vorhandensein 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 Beispiel eines Denkmals, das Folien mit Diagrammen erstellt.

Konvertierung von Folien in PDF

Obwohl die HTML-Version der Folien vollkommen autark ist, kann es dennoch erforderlich sein, auch eine PDF-Version der Folien zu haben. Erstens passiert es, dass einige Konferenzen, die dem Referenten nicht erlauben, seinen eigenen Laptop anzuschließen, die Folien „ausschließlich im Format pptx oder pdf“ verlangen, ohne zu erwarten, dass sie auch in HTML vorliegen. Zweitens ist es guter Stil, den Organisatoren eine unveränderbare Variante Ihrer Folien in der Form zu schicken, in der sie bei der Präsentation gezeigt wurden, im PDF-Format zur Veröffentlichung der Datei in den Konferenzmaterialien.

Glücklicherweise bewältigt dieses Aufgabe das Node.js-Tool decktape, das auf Puppeteer — einem Automatisierungssystem zur Steuerung des Browsers Chrome — basiert. Um eine RevealJS-Präsentation in PDF zu konvertieren, kann der Befehl verwendet werden.

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

Zwei Tricks beim Start von decktape, zu denen ich durch Ausprobieren gekommen bin:

Auflösung über Parameter -s Man muss mit einem zweifachen Puffer rechnen, sonst können Probleme mit den Konvertergebnissen auftreten.
Im URL der HTML-Version der Präsentation muss ein Parameter übergeben werden. ?fragments=true, was es ermöglicht, für jeden Zwischenstatus Ihrer Folie eine separate PDF-Seite zu erstellen (zum Beispiel fünf Seiten für fünf Punkte der Liste, wenn sie nacheinander angezeigt werden). Dies ermöglicht es, dieses PDF selbst als Präsentation während eines Vortrags zu verwenden.

Automatische Erstellung und Veröffentlichung im Web

Es ist praktisch, wenn Folien automatisch erstellt werden, wenn Änderungen im Versionskontrollsystem vorgenommen werden, und noch praktischer, wenn die automatisch kompilierten Folien im Internet für die allgemeine Nutzung bereitgestellt werden. Folien aus dem Internet können leicht von jedem mit dem Internet und einem Projektor verbundenen Gerät vor einem Publikum „abgespielt“ werden.

Da wir in unserer Arbeit GitHub verwenden, ist eine natürliche 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 .gihub.io/.

Die vollständige Konfigurationsdatei für TravisCI, die die Erstellung der HTML-Version der Seite mit Maven, die Konvertierung in PDF mit decktape und das Hochladen der Ergebnisse in den Branch gh-pages zum Veröffentlichen auf github.io, sieht aus so.

Um ein solches Projekt auf der TravisCI-Seite zu erstellen, müssen Umgebungsvariablen konfiguriert werden.

GH_REF — Wert im Format github.com/inponomarev/csa-hb
GH_TOKEN — Zugriffstoken für GitHub. Kann in GitHub in den Einstellungen Ihres Profils, Entwickleroptionen -> Persönliche Zugriffstoken, erhalten werden. Wenn Sie die Präsentation in ein öffentliches Repository hochladen, reicht es für dieses Token aus, nur das Zugriffslevel „Zugriff auf öffentliche Repositories“ anzugeben.
GH_USER_EMAIL / GH_USER_NAME — Paar Name/E-Mail, unter dem der Push in den Branch erfolgen wird. gh-pages.

Somit führt jeder Code-Commit der Präsentation auf GitHub zu einer automatischen Neubearbeitung der Folien in den Formaten HTML und PDF und deren erneuten Hochladen auf github.io. (Natürlich sollten nur die Präsentationen, die Sie letztendlich öffentlich machen möchten, auf github.io hochgeladen werden.)

Beispiele für Projekte

Abschließend – Links zu ein paar Beispielen von Präsentationsprojekten mit konfigurierten Maven-Skripten und CI-Konfiguration für Travis-CI, die man klonen und verwenden kann, um eigene Präsentationsprojekte zu erstellen: