🥇Presentazione come codice, o perché non uso più Powerpoint

Sembra che nel corso della mia carriera nel IT abbia realizzato decine di presentazioni per colleghi, clienti e interventi pubblici. Per molti anni, PowerPoint è stato per me una scelta naturale e affidabile per creare slide. Ma quest'anno la situazione è cambiata radicalmente. Da febbraio a maggio, ho avuto l'opportunità di parlare a cinque conferenze, e dovevo preparare le slide in tempi stretti, ma con qualità. È emersa così la necessità di delegare la parte del lavoro relativa al design visivo delle slide ad altre persone. Una volta ho provato a lavorare con un designer, inviando file .pptx via e-mail, ma il lavoro si è trasformato in caos: nessuno sapeva quale versione delle slide fosse “l'ultima”, e il layout si rovinava a causa delle diverse versioni di PowerPoint e dei font sulle nostre macchine. Così ho deciso di provare qualcosa di nuovo. L'ho fatto 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 la documentazione di progetto, affrontando gli stessi problemi: sebbene Word sia ottimo per redigere un documento breve, con l'aumento del volume sorgono difficoltà nella collaborazione e nell'ottenere un formato di qualità e uniforme. La nostra scelta è caduta su AsciiDoctor, e ne siamo ancora felici, ma questo meriterebbe un articolo a parte. Circa in quel periodo abbiamo scoperto l'efficacia di uno dei principi DevOps, “everything as code”, quindi la scelta delle specifiche per la nuova tecnologia di creazione delle slide è stata piuttosto ovvia:

La presentazione deve essere un file di testo semplice in un linguaggio di markup.
Le slide riguardano progetti di sviluppo, quindi il markup deve consentire di inserire facilmente, senza dover ricorrere a sistemi esterni,
- frammenti di codice con evidenziazione della sintassi,
- diagrammi semplici sotto forma di figure geometriche collegate da frecce,
- diagrammi UML, flowchart e altro.
Il progetto della presentazione deve essere memorizzato in un sistema di controllo versioni.
La convalida e la generazione delle slide pronte devono avvenire in un sistema CI.

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

Sebbene io preferisca LaTeX, la mia mente suggeriva che la scelta di una soluzione utilizzata non solo da me dovesse cadere su una soluzione familiare a un pubblico più ampio. Non tutti conoscono LaTeX, e se la tua pratica quotidiana non è legata alla scrittura di articoli scientifici, difficilmente troverai il tempo per addentrarti nel vasto e complesso mondo di questo sistema.

Tuttavia, anche la padronanza di HTML/CSS non è esattamente un'abilità diffusa: ad esempio, io non la possiedo completamente. Fortunatamente, qui ci viene in aiuto AsciiDoctor: il convertitore asciidoctor-revealjs consente di creare slide RevealJS utilizzando la sintassi di AsciiDoctor. E questa è facile da apprendere e accessibile a tutti!

Come codificare le slide

Per comprendere il concetto di codifica delle slide in AsciiDoctor, è più semplice fornire esempi concreti. Tutti provengono da slide reali che ho fatto per le mie presentazioni a conferenze quest'anno.

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

== Perché ci serve lo Streams API?

[%step]
* Elaborazione di stream in tempo reale
* API stile stream (map / reduce)
* Sotto il cofano:
** Commit automatico degli offset
** Re-bilanciamento
** Stato interno dei gestori
** Scalabilità semplice

Risultato

Titolo e frammento di codice con evidenziazione della sintassi:

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

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

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

Risultato

Durante la preparazione per la mia presentazione, i frammenti di codice dimostrativi sono soggetti a ripetute modifiche e miglioramenti, quindi è inestimabile la possibilità di copiare e incollare rapidamente il “codice grezzo” direttamente nella slide, garantendo l'attualità del esempio dimostrativo senza preoccuparsi dell'evidenziazione della sintassi.

Titolo, illustrazione e testo (effettuiamo il layout 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 semplicemente un'immagine a tutto schermo:

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

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

Risultato

Spesso è necessario supportare un'idea con un semplice diagramma, sotto forma di “scatole collegate da frecce”. Fortunatamente, AsciiDoctor è integrato con il sistema Graphviz — un linguaggio che permette di descrivere diagrammi a grafo sulla base della descrizione di nodi e collegamenti tra di essi. È necessario familiarizzare con Graphviz, ma con gli esempi esistenti è piuttosto semplice! Ecco come appare:

== Scriviamo “Bet Totalling App”

Qual è l'importo delle vincite per le scommesse effettuate se si verifica l'esito?

[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 sia necessario modificare l'etichetta su una figura, cambiare la direzione della freccia e così via — è possibile farlo direttamente nel codice della presentazione, invece di ridisegnare l'immagine da qualche parte e reinserirla nella diapositiva. Questo aumenta notevolmente la velocità di lavoro sulle diapositive.

Un 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 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;}
}
-----

Risultato

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

Infine, se è necessario inserire un diagramma di flusso, un diagramma delle classi o un altro diagramma standardizzato nella diapositiva, in questo caso può essere utile un altro sistema integrato con AsciiDoctor, PlantUML. Sulle ampie possibilità di PlantUML il mio collega Nikolai Potashnikov ha scritto un post separato.

Trasformare il progetto della presentazione in codice memorizzato nel sistema di controllo versioni consente di organizzare il lavoro collaborativo sulla presentazione, principalmente separando i compiti di creazione dei contenuti e di design. La progettazione delle diapositive (font, sfondi, margini) in RevealJS viene descritta tramite CSS. La mia capacità personale di gestire CSS è meglio rappresentata da questo gif — ma non è un problema quando ci sono persone che lavorano con CSS molto più abilmente e rapidamente di me. Alla fine, si scopre che nell'ambito di una scadenza di presentazione incombente, possiamo lavorare simultaneamente su file diversi tramite Git e aumentare la velocità della collaborazione, impossibile con l'invio di file .pptx via email.

Assemblaggio della pagina HTML con le diapositive

Gli origini in testo semplice sono buone, ma come possono essere compilati nella presentazione stessa?

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

Se non si vuole affrontare l'installazione di Ruby, è possibile utilizzare un'immagine docker asciidoctor/docker-asciidoctor, in cui all'avvio si può collegare la cartella con le origini del progetto tramite VOLUME e ottenere il risultato nel punto desiderato.

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 disponibilità di Docker, ma consente di generare diapositive tramite uno script Maven.

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

Disponibilità asciidoctor-maven-plugin consente di assemblare la documentazione AsciiDoctor, che è parte di un progetto Java (di cui facciamo ampio uso). Inoltre, AsciiDoctor e JRuby vengono scaricati automaticamente da Maven, e AsciiDoctor viene eseguito nell'ambiente JRuby: non è necessario installare nulla sulla macchina! (Ad eccezione del pacchetto graphviz, necessario se si desidera utilizzare la grafica GraphViz o PlantUML.) È sufficiente posizionare i propri file .adoc nella cartella src/main/asciidoc/. Ecco un esempio di monumento, che compila le diapositive con i diagrammi.

Conversione delle diapositive in PDF

Sebbene la versione HTML delle diapositive sia completamente autonoma, è comunque necessario avere anche una versione PDF delle diapositive. In primo luogo, succede che in alcune conferenze, che non offrono all'oratore la possibilità di collegare il proprio laptop, richiedano le diapositive "esclusivamente in formato pptx o pdf", senza aspettarsi che esistano anche in HTML. In secondo luogo, è buona norma inviare agli organizzatori una versione immutabile delle proprie diapositive nella forma in cui sono state presentate nel discorso, in formato PDF per la pubblicazione del file nei materiali della conferenza.

Fortunatamente, questo compito è affrontato dall'utility Node.js decktape, costruita sulla base di Puppeteer — un sistema di automazione per il controllo del browser Chrome. Per convertire una presentazione RevealJS in PDF, si può utilizzare il comando

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

Due suggerimenti per l'avvio di decktape, ai quali sono arrivato attraverso tentativi ed errori:

risoluzione tramite parametro -s devi impostare un margine doppio, altrimenti potrebbero sorgere problemi con i risultati della conversione
nella URL della versione HTML della presentazione deve essere passato un parametro ?fragments=true, che consente di creare una pagina PDF separata per ogni stato intermedio del tuo slide (ad esempio, cinque pagine per cinque punti in un elenco, se vengono mostrati uno dopo l'altro). Questo permetterà di utilizzare quel PDF come una presentazione autonoma durante il discorso.

Compilazione automatica e pubblicazione online

È comodo quando le diapositive vengono compilate automaticamente allorché ci sono cambiamenti nel sistema di controllo versione, ed è ancora più comodo quando le diapositive compilate automaticamente vengono caricate online per l'uso pubblico. Le diapositive da Internet possono essere facilmente 'riprodotte' davanti al pubblico da qualsiasi macchina collegata a Internet e a un proiettore.

Poiché utilizziamo GitHub nel nostro lavoro, la scelta naturale per il sistema CI è TravisCI, e per l'hosting delle presentazioni pronte — github.io. L'idea di github.io è che qualsiasi contenuto statico messo 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 usando Maven, la conversione in PDF tramite decktape e il caricamento dei risultati nel ramo gh-pages per la pubblicazione su github.io, appare così.

Per compilare un progetto di questo tipo sul lato TravisCI, è necessario configurare le variabili d'ambiente

GH_REF — un valore del tipo github.com/inponomarev/csa-hb
GH_TOKEN — il token di accesso a GitHub. Può essere ottenuto in GitHub nelle impostazioni del proprio profilo, Impostazioni sviluppatore -> Token di accesso personale. Se pubblichi la presentazione in un repository pubblico, per questo token è sufficiente impostare il livello di accesso 'Accesso a repository pubblici'.
GH_USER_EMAIL / GH_USER_NAME — coppia nome/email, a nome della quale verrà effettuato il push nel ramo gh-pages.

In questo modo, ogni commit del codice della presentazione su GitHub porta alla ricompilazione automatica delle diapositive nei formati HTML e PDF e al loro ricaricamento su github.io. (Naturalmente, si devono caricare su github.io solo quelle presentazioni che desideri rendere pubbliche.)

Esempi di progetti

Infine, ecco i link 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: