🥇Presentazione come codice, o Perché non uso più PowerPoint

Mi sembra di aver fatto decine di presentazioni per colleghi, clienti e discorsi pubblici nella mia carriera nel settore IT. Per molti anni PowerPoint è stato per me una scelta naturale e affidabile per creare diapositive. Ma quest'anno la situazione è cambiata qualitativamente. Da febbraio a maggio ho avuto l'opportunità di parlare a cinque conferenze, e le diapositive per le presentazioni dovevano essere preparate in tempi stretti, ma di alta qualità. Si è posto il problema di delegare la parte del lavoro che riguarda il design visivo delle diapositive ad altre persone. Una volta ho provato a lavorare con un designer, inviando file .pptx via email, ma il lavoro è diventato una confusione: nessuno sapeva quale versione delle diapositive fosse "l'ultima", e il layout era in disordine a causa delle diverse versioni di PowerPoint e dei font sui nostri computer. Così ho deciso di provare qualcosa di nuovo. Ho provato, e da allora non penso di tornare a PowerPoint.

Cosa vogliamo

Circa un anno e mezzo fa, nella nostra azienda abbiamo smesso di usare Word per creare documentazione progettuale, affrontando gli stessi problemi: sebbene Word sia buono per scrivere un piccolo documento, con il crescere dei volumi, sorgono difficoltà nella collaborazione e nell'ottenere un formato di qualità e unificato. La nostra scelta è ricaduta su AsciiDoctor, e non smettiamo di essere felici per questa scelta, ma questo è un argomento per un articolo a parte. Circa in quel periodo abbiamo appreso l'efficacia di uno dei principi DevOps "tutto come codice", quindi la scelta dei requisiti per la nuova tecnologia di creazione di diapositive era abbastanza ovvia:

La presentazione deve essere un file di testo semplice in un linguaggio di markup.
Le diapositive trattano i progetti di sviluppo, quindi il markup deve consentire di inserire facilmente, senza ricorrere a sistemi esterni,
- frammenti di codice con evidenziazione della sintassi,
- diagrammi semplici a forma di figure geometriche collegate da frecce,
- diagrammi UML, flowchart e altro.
Il progetto della presentazione deve essere memorizzato nel sistema di controllo delle versioni.
La validazione e la creazione delle diapositive finite devono essere eseguite in un sistema CI.

Ad oggi, esistono due opzioni di base per creare diapositive in linguaggi di markup: il pacchetto beamer per LaTeX o uno dei framework per creare diapositive in HTML/CSS (RevealJS, remark, deck.js e molti altri).

Anche se la mia anima è attratta da LaTeX, la ragione suggeriva che la scelta della soluzione che userò non dovrei essere solo io a farla, dovrebbe essere dalla parte di una soluzione conosciuta da un pubblico più ampio. Non tutti conoscono LaTeX e se la tua pratica quotidiana non è legata alla scrittura di articoli scientifici, è improbabile che tu possa trovare il tempo per immergerti nel vasto e complesso mondo di questo sistema.

Tuttavia, la padronanza di HTML/CSS non è esattamente una competenza comune: io, per esempio, non lo padroneggio affatto completamente. Fortunatamente, qui arriva in aiuto il nostro già noto AsciiDoctor: il convertitore asciidoctor-revealjs permette di creare diapositive RevealJS usando la markup di AsciiDoctor. E questa è davvero facile da apprendere e accessibile a tutti!

Come codificare le diapositive

Per capire l'essenza della codifica delle diapositive in AsciiDoctor, è più semplice portare esempi concreti. Tutti sono tratti da diapositive reali che ho realizzato per le mie conferenze quest'anno.

Una diapositiva con un titolo e un elenco di punti che si aprono uno dopo l'altro:

== Perché abbiamo bisogno delle Streams API?

[%step]
* Elaborazione dei flussi in tempo reale
* API simili a flussi (map / reduce)
* Sotto il cofano:
** Commit automatico dell'offset
** Ribilanciamento
** Stato interno dei gestori
** Facile scalabilità

Risultato

Titolo e frammento di codice sorgente con evidenziazione della sintassi:

== Kafka Streams API: struttura generale di un'app KStreams

[source,java]
----
StreamsConfig config = ...;
// Qui impostiamo varie opzioni

Topology topology = new StreamsBuilder()
// Qui costruiamo la topologia
....build();
----

Risultato

Durante la preparazione della presentazione, i codici di esempio vengono sottoposti a molteplici revisioni e miglioramenti, quindi è inestimabile avere la possibilità di copiare e incollare rapidamente il "codice grezzo" direttamente nella diapositiva, garantendo la pertinenza dell'esempio dimostrativo e senza preoccuparsi dell'evidenziazione della sintassi.

Titolo, illustrazione e testo (disponiamo il contenuto nella tabella AsciiDoctor):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, Novembre 2018
* Esempi di codice per Kafka 1.0
|===

Risultato

A volte non è necessario un titolo, e per illustrare il tuo pensiero serve solo un'immagine a tutto campo:

[%notitle]
== Vivere nel legacy non è facile

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

Risultato

Spesso è necessario supportare un'idea con un diagramma semplice, sotto forma di "scatole collegate da frecce". Fortunatamente, AsciiDoctor è integrato con il sistema Graphviz — un linguaggio che consente di descrivere i diagrammi a grafo sulla base della descrizione dei nodi e delle connessioni tra di essi. È necessario imparare a utilizzare Graphviz, ma farlo sulla base degli esempi esistenti è abbastanza facile! Ecco come appare:

== Scriviamo "Bet Totalling App"

Qual è l'importo delle vincite sulle scommesse effettuate se l'esito è favorevole?

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

Risultato

Nel caso in cui sia necessario modificare l'etichetta su una figura, cambiare la direzione della freccia, ecc. — questo può essere fatto direttamente nel codice della presentazione, invece di ridisegnare un'immagine altrove e reinserirla nella diapositiva. Questo aumenta notevolmente la velocità di lavoro sulle diapositive.

Esempio più complesso:

== Assemblaggio non riproducibile
[graphviz, "unstable-update.png"]
-----
digraph G {
  rankdir="LR";
  graph [ dpi = 150 ];
  u -> r0;
  u[shape=plaintext; label="linter updaten+ 13 avvisi"]
  r0[shape=point, width = 0]
  r1 -> r0[ arrowhead = none, label="ramo master" ];
  r0-> r2 [];   b1 -> b4;  r1->b1
  r1[label="150n avvisi"]
  b1[label="± 0n avvisi"]
  b4[label="± 0n avvisi"]
  b4->r2
  r2[label="163n avvisi", color="red", xlabel=<<font color="red">merge bloccato<\/font>>]
  {rank = same; u; r0; b4;}
}
-----

Risultato

A proposito, è comodo sperimentare con Graphviz e debugare le immagini sulla pagina Graphviz online.

Infine, se è necessario inserire nel diapositiva un diagramma di flusso, un diagramma delle classi o un altro diagramma standardizzato, in questo caso può essere d'aiuto un altro sistema integrato con AsciiDoctor, PlantUML. Il mio collega Nikolaj Potašnikov ha scritto riguardo alle ampie capacità di PlantUML post separato.

Trasformare il progetto di presentazione in codice, conservato nel sistema di controllo delle versioni, consente di organizzare il lavoro collaborativo sulla presentazione, prima di tutto separando i compiti di creazione dei contenuti e di progettazione. La progettazione delle diapositive (font, sfondi, margini) in RevealJS è descritta utilizzando CSS. La mia personale abilità nel gestire CSS è meglio trasmessa da questa gif — ma non è un problema, quando ci sono persone che lavorano con CSS molto più abilmente e velocemente di me. Di conseguenza, possiamo lavorare contemporaneamente su file diversi tramite Git e aumentare la velocità di collaborazione, impossibile con l'invio di file .pptx via email.

Assemblaggio della pagina HTML con le diapositive

I sorgenti di testo semplice sono fantastici, ma come compilarli nella presentazione stessa?

AsciiDoctor è un progetto scritto in Ruby e può essere avviato in diversi modi. Innanzitutto, puoi installare il linguaggio Ruby e avviare asciidoctor direttamente, il che sarà probabilmente il modo più vicino agli sviluppatori Ruby.

Se non vuoi occuparti dell'installazione di Ruby, puoi usare un'immagine docker asciidoctor/docker-asciidoctor, in cui puoi collegare la cartella con i sorgenti del progetto tramite VOLUME al momento dell'avvio e ottenere il risultato nel posto designato.

L'opzione su cui mi sono fermato può sembrare un po' inaspettata, ma è la più comoda per me come sviluppatore Java. Non richiede né l'installazione di Ruby né la presenza di Docker, ma consente di generare diapositive utilizzando uno script Maven.

Il fatto è che il progetto JRuby — l'implementazione Java del linguaggio Ruby — è così buono da consentire di eseguire nella macchina Java praticamente tutto ciò che è stato creato per Ruby, e l'esecuzione di AsciiDoctor è uno degli usi più comuni di JRuby.

La presenza di asciidoctor-maven-plugin permette di raccogliere la documentazione AsciiDoctor, che fa parte di un progetto Java (di cui facciamo ampio uso). In questo caso, AsciiDoctor e JRuby vengono scaricati automaticamente dal Maven, e AsciiDoctor viene eseguito nell'ambiente JRuby: non è necessario installare nulla sulla macchina! (A parte il pacchetto graphviz, che è necessario se desideri utilizzare grafica GraphViz o PlantUML.) Basta posizionare i tuoi file .adoc nella cartella src/main/asciidoc/. Ecco esempio di monumento, che raccoglie diapositive con diagrammi.

Conversione delle diapositive in PDF

Anche se la versione HTML delle diapositive è abbastanza autonoma, avere anche una versione PDF delle diapositive è a volte necessario. In primo luogo, può avvenire che in alcune conferenze, che non offrono al relatore la possibilità di collegare il proprio laptop, richiedano le diapositive "rigorosamente nel formato pptx o pdf", senza aspettarsi che ci siano anche in HTML. In secondo luogo, è buona educazione inviare agli organizzatori una copia invariata delle diapositive che sono state mostrate durante la presentazione, in formato PDF per la pubblicazione del file nei materiali della conferenza.

Fortunatamente, questa attività è gestita dallo strumento Node.js decktape, costruito sulla base di Puppeteer — un sistema di automazione per il controllo del browser Chrome. Puoi convertire una presentazione RevealJS in PDF con il comando

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

Due trucchi per avviare decktape, a cui sono arrivato mediante tentativi ed errori:

autorizzazione tramite parametro -s deve essere impostata con un margine doppio, altrimenti potrebbero sorgere problemi con i risultati della conversione
nella URL della versione HTML della presentazione deve essere passato il parametro ?fragments=true, il che consentirà di creare una pagina PDF separata per ciascuno stato intermedio della tua diapositiva (ad esempio, cinque pagine per cinque punti elenco, se vengono visualizzati uno dopo l'altro). Questo permetterà di utilizzare tale PDF da solo come presentazione durante una relazione.

Assemblaggio automatico e pubblicazione sul web

È comodo quando le diapositive vengono assemblate automaticamente quando ci sono modifiche nel sistema di controllo delle versioni, ed è ancora più comodo quando le diapositive compilate automaticamente vengono pubblicate su Internet per l'uso pubblico. Le diapositive da Internet possono essere facilmente 'eseguite' davanti al pubblico da qualsiasi macchina connessa a Internet e a un proiettore.

Poiché utilizziamo GitHub nel nostro lavoro, la scelta naturale del sistema CI è TravisCI, e per l'hosting delle presentazioni pronte — github.io. L'idea di github.io è che qualsiasi contenuto statico inserito nel ramo gh-pages del tuo progetto su GitHub diventa accessibile all'indirizzo .gihub.io/.

Il file di configurazione completo di TravisCI, che include la compilazione della versione HTML della pagina tramite Maven, la conversione in PDF usando decktape e il caricamento dei risultati nel ramo gh-pages per la pubblicazione su github.io, appare così.

Per assemblare un tale progetto lato TravisCI è necessario configurare le variabili ambientali

GH_REF — valore del tipo github.com/inponomarev/csa-hb
GH_TOKEN — token di accesso a GitHub. Può essere ottenuto su GitHub nelle impostazioni del proprio profilo, Developer Settings -> Personal Access Tokens. Se pubblichi la presentazione in un repository pubblico, è sufficiente specificare per questo token solo il livello di accesso "Access public repositories".
GH_USER_EMAIL / GH_USER_NAME — coppia nome/email, sotto cui verrà eseguito il push nel ramo gh-pages.

In questo modo, ogni commit del codice della presentazione su GitHub porta alla ricostruzione automatica delle diapositive nei formati HTML e PDF e al loro ricaricamento su github.io. (Naturalmente, è necessario caricare su github.io solo le presentazioni che si desidera rendere pubbliche alla fine.)

Esempi di progetti

Infine, ecco i collegamenti a un paio di esempi di progetti di presentazione con script Maven configurati e configurazione CI per Travis-CI, che possono essere clonati e utilizzati per creare i propri progetti di presentazione: