Il semble que j'ai eu la chance de faire des dizaines de présentations pour des collègues, des clients et des apparitions publiques pour ma carrière en informatique. Pendant de nombreuses années, Powerpoint, en tant que moyen de fabrication de diapositives, est resté pour moi un choix naturel et fiable. Mais cette année, la situation a changé qualitativement. De février à mai, j'ai eu l'occasion de prendre la parole lors de cinq conférences et les diapositives des rapports ont dû être préparées en peu de temps, mais avec une grande qualité. La question s'est posée de déléguer cette partie du travail, comme pour la conception visuelle des diapositives, à d'autres personnes. Une fois, j'ai essayé de travailler avec un concepteur en envoyant des fichiers .pptx par courrier, mais le travail s'est transformé en chaos: personne ne savait quelle version des diapositives était "la plus récente", et la mise en page "est allée" en raison de la différence entre les versions Powerpoint et les polices sur nos machines . Et j'ai décidé d'essayer quelque chose de nouveau. Je l'ai essayé, et depuis lors je ne pense pas à revenir sur Powerpoint.
Que voulons-nous
Il y a environ un an et demi, nous, dans l'entreprise, avons refusé d'utiliser Word pour créer la documentation de projet, confrontés aux mêmes problèmes: bien que Word soit bon pour taper un petit document, à mesure que les volumes augmentent, il est difficile de travailler ensemble et d'obtenir une conception unifiée et de haute qualité. Notre choix s'est porté sur AsciiDoctor , et nous ne cessons de nous réjouir de ce choix, mais c'est un sujet pour un article séparé. À peu près à la même époque, nous avons appris l'efficacité de l'un des principes DevOps de "tout comme du code", de sorte que le choix des exigences pour la nouvelle technologie de création de diapositives de présentation était assez évident:
- La présentation doit être un fichier texte brut dans un langage de balisage.
- Nous avons des diapositives sur les projets de développement, donc le balisage devrait vous permettre de vous insérer facilement sans recourir à des systèmes externes
- fragments de code mis en évidence par la syntaxe,
- schémas simples sous forme de formes géométriques reliées par des flèches,
- Diagrammes UML, organigrammes, etc.
- Le projet de présentation doit être stocké dans un système de contrôle de version.
- La validation et l'assemblage des lames finies doivent être effectués dans le système CI.
Aujourd'hui, il existe deux options de base pour créer des diapositives dans les langages de balisage: le package beamer pour LaTeX ou l'un des cadres de création de diapositives en HTML / CSS ( RevealJS , remarque , deck.js et bien d'autres).
Bien que mon âme soit avec LaTeX, mon esprit a suggéré que le choix d'une solution que je n'utiliserai pas seul devrait être du côté de la solution, familier à un cercle plus large de personnes. Tout le monde ne connaît pas LaTeX, et si votre pratique quotidienne n'est pas liée à la rédaction d'articles scientifiques, il est peu probable que vous ayez le temps de vous immerger dans le monde vaste et complexe de ce système.
Cependant, la maîtrise du HTML / CSS ne veut pas dire que la compétence omniprésente est: moi, par exemple, je ne la possède pas entièrement. Heureusement, le familier AsciiDoctor vient à la rescousse: le convertisseur asciidoctor-révélerjs vous permet de créer des diapositives RevealJS à l'aide du balisage AsciiDoctor. Et c'est tellement facile à apprendre et accessible à tous!
Comment encoder des diapositives
Pour comprendre l'essence du codage des diapositives sur AsciiDoctor, il est plus facile de donner des exemples spécifiques. Tous sont tirés de véritables diapositives que j'ai faites pour mes conférences cette année.
Une diapositive avec un en-tête et une liste l'un après l'autre des premiers paragraphes:
== Streams API? [%step] * Real-time stream processing * Stream-like API (map / reduce) * : ** offset commit ** ** **
En-tête et extrait de code source avec mise en évidence de la syntaxe:
== Kafka Streams API: KStreams- [source,java] ---- StreamsConfig config = ...; // Topology topology = new StreamsBuilder() // ....build(); ----
Au cours de la préparation du rapport, les exemples de code de démonstration subissent des modifications et des améliorations répétées, donc la capacité inestimable de copier et coller rapidement le "code brut" directement dans la diapositive, garantissant la pertinence de l'exemple de démonstration et ne se souciant pas de la coloration syntaxique.
Le titre, l'illustration et le texte (la mise en page sur la diapositive est réalisée dans les cellules du tableau AsciiDoctor ):
== Kafka Streams in Action [.custom-style] [cols="30a,70a"] |=== |image::KSIA.jpg[] | * **William Bejeck**, + “Kafka Streams in Action”, November 2018 * Kafka 1.0 |===
Parfois, le titre n'est pas nécessaire, mais pour illustrer vos pensées, vous avez juste besoin d'une image en plein écran:
[%notitle] == image::swampman.jpg[canvas, size=cover]
Souvent, l'idée doit être appuyée par un schéma simple, sous la forme de «carrés reliés par des flèches». Heureusement, AsciiDoctor est intégré au système Graphviz , un langage qui vous permet de décrire des diagrammes de graphiques en fonction des descriptions des sommets et des relations entre eux. Graphviz doit être maîtrisé, mais sur la base d'exemples existants, c'est assez simple! Voici à quoi ça ressemble:
== “Bet Totalling App” , ? [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="Local Store"; fixedsize="true"; width="1.5"] Source -> MapVal -> Sum -> Sink Sum -> Store [dir=both; label=" \n "] {rank = same; Store; Sum;} } -----
Dans le cas où il est nécessaire de modifier la signature sur la figure, de changer le sens de la flèche, etc., cela peut être fait directement dans le code de présentation, au lieu de redessiner l'image quelque part et de la réinsérer dans la diapositive. Cela augmente considérablement la vitesse de travail sur les diapositives.
Un exemple est plus compliqué:
== [graphviz, "unstable-update.png"] ----- digraph G { rankdir="LR"; graph [ dpi = 150 ]; u -> r0; u[shape=plaintext; label="linter update\n+ 13 warnings"] r0[shape=point, width = 0] r1 -> r0[ arrowhead = none, label="master branch" ]; r0-> r2 []; b1 -> b4; r1->b1 r1[label="150\nwarnings"] b1[label="± 0\nwarnings"] b4[label="± 0\nwarnings"] b4->r2 r2[label="163\nwarnings", color="red", xlabel=<<font color="red">merge blocked</font>>] {rank = same; u; r0; b4;} } -----
Soit dit en passant, expérimenter avec Graphviz et déboguer des images est pratique sur la page en ligne de Graphviz .
Enfin, si vous devez insérer un diagramme, un diagramme de classes ou un autre diagramme normalisé dans la diapositive, un autre système intégré à AsciiDoctor, PlantUML , peut venir à la rescousse . Mon collègue Nikolai Potashnikov a écrit un article séparé sur les vastes capacités de PlantUML.
La transformation du projet de présentation en code stocké sur le système de contrôle de version permet d'organiser un travail commun sur la présentation, tout d'abord, pour séparer les tâches de création de contenu et de conception. La conception des diapositives (polices, arrière-plans, retraits) dans RevealJS est décrite à l'aide de CSS. Ma compétence CSS personnelle est mieux véhiculée par ce GIF - mais ce n'est pas effrayant quand il y a des gens qui travaillent avec CSS beaucoup plus agile et plus rapide que moi. En conséquence, il s'avère que dans le contexte d'une date limite de présentation qui approche rapidement, nous pouvons simultanément travailler sur différents fichiers via Git et développer la vitesse de collaboration qui est impossible lors de l'envoi de fichiers .pptx par courrier.
Créez une page HTML avec des diapositives
Les sources en texte brut sont excellentes, mais comment les compilez-vous dans la présentation elle-même?
AsciiDoctor est un projet Ruby et vous pouvez l'exécuter de plusieurs manières. Tout d'abord, vous pouvez installer le langage Ruby et exécuter directement asciidoctor, qui sera probablement le plus proche des développeurs Ruby.
Si vous ne souhaitez pas vous impliquer dans l'installation de Ruby, vous pouvez utiliser l'image docker asciidoctor / docker-asciidoctor , dans laquelle vous pouvez connecter le dossier source du projet via VOLUME et obtenir le résultat à l'emplacement spécifié.
L'option sur laquelle j'ai opté peut sembler quelque peu inattendue, mais elle me convient le mieux en tant que développeur Java. Il ne nécessite pas l'installation de Ruby ou docker, mais vous permet de générer des diapositives à l'aide d'un script Maven.
Le fait est que le projet JRuby - l'implémentation Java du langage Ruby - est si bon qu'il vous permet d'exécuter presque tout ce qui est créé pour Ruby dans la machine Java, et exécuter AsciiDoctor est l'une des applications JRuby les plus courantes.
La présence du plugin asciidoctor-maven vous permet de collecter la documentation AsciiDoctor, qui fait partie du projet Java (que nous utilisons activement). En même temps, AsciiDoctor et JRuby sont téléchargés automatiquement par Maven, et AsciiDoctor est exécuté dans l'environnement JRuby: rien ne doit être installé sur la machine! (À l' graphviz package graphviz , qui est nécessaire si vous souhaitez utiliser des graphiques GraphViz ou PlantUML.) Placez simplement vos fichiers .adoc dans le dossier src/main/asciidoc/ . Voici un exemple de pickhouse collectant des diapositives de diagramme.
Convertir des diapositives en PDF
Bien que la version HTML des diapositives soit complètement autosuffisante, il est toujours nécessaire d'avoir une version PDF des diapositives. Premièrement, il arrive que lors de certaines conférences qui n'offrent pas au locuteur la possibilité de connecter son propre ordinateur portable, elles nécessitent des diapositives «strictement au format pptx ou pdf», sans s'attendre à ce qu'elles soient également disponibles en HTML. Deuxièmement, il est bon d'envoyer aux organisateurs une version inchangée de vos diapositives sous la forme telle qu'elle figurait sur le rapport, au format PDF pour la publication du fichier dans les documents de la conférence.
Heureusement, Node.js est un utilitaire de création de bande construit sur la base de Puppeteer , le système d'automatisation du navigateur Chrome, qui gère cette tâche. Vous pouvez convertir la présentation RevealJS au format PDF avec la commande
node decktape.js -s 3200x1800 --slides 1-500 \ reveal "file:///index.html?fragments=true" slides.pdf
Deux astuces pour démarrer le decktape, qui devaient venir par essais et erreurs:
la résolution via le paramètre -s doit être définie avec une double marge, sinon il peut y avoir des problèmes avec les résultats de la conversion
dans l'URL de la version HTML de la présentation, vous devez passer le paramètre ?fragments=true , qui vous permettra de créer une page PDF distincte pour chaque état intermédiaire de votre diapositive (par exemple, cinq pages pour cinq éléments de liste, s'ils s'affichent les uns après les autres). Cela permettra l'utilisation d'un tel PDF en tant que présentation dans un rapport.
Création et publication automatiques sur le Web
C'est pratique lorsque les diapositives sont collectées automatiquement lorsque les modifications tombent dans le système de contrôle de version, et encore plus pratique lorsque les diapositives compilées automatiquement sont publiées sur Internet pour une utilisation générale. Les diapositives d'Internet peuvent être facilement «lues» devant un public à partir de n'importe quelle machine connectée à Internet et au projecteur.
Puisque nous utilisons GitHub dans notre travail, le choix naturel pour le système CI est TravisCI , et pour l'hébergement de présentations toutes faites - imtqy.com . L'idée de imtqy.com est que tout contenu statique placé dans la branche gh-pages de votre projet sur GitHub devient disponible à < >.gihub.io/< > .
Le fichier de configuration TravisCI complet, y compris la compilation de la version HTML de la page à l'aide de Maven, la conversion au format PDF à l'aide de decktape et le téléchargement des résultats vers la branche gh-pages pour publication sur imtqy.com, ressemble à ceci .
Pour construire un tel projet du côté de TravisCI, vous devez configurer les variables d'environnement
GH_REF - valeur du formulaire github.com/inponomarev/csa-hbGH_TOKEN - Jeton d'accès GitHub. Vous pouvez l'obtenir sur GitHub dans vos paramètres de profil, Paramètres développeur -> Jetons d'accès personnels. Si vous téléchargez la présentation dans un référentiel public, pour ce jeton, il suffit de spécifier le seul niveau d'accès "Accéder aux référentiels publics".GH_USER_EMAIL / GH_USER_NAME - paire nom / mail, pour le compte de laquelle le push vers la branche gh-pages sera implémenté.
Ainsi, chaque commit du code de présentation sur GitHub reconstruira automatiquement les diapositives aux formats HTML et PDF et les rechargera sur imtqy.com. (Bien sûr, seules les présentations que vous souhaitez rendre publiques à la fin doivent être téléchargées sur imtqy.com.)
Exemples de projets
Enfin, il existe des liens vers quelques exemples de projets de présentation avec des scripts Maven personnalisés et une configuration CI pour Travis-CI, que vous pouvez cloner et utiliser lors de la création de vos propres projets de présentation:
Au revoir Powerpoint! Je ne pense pas avoir besoin de vous pour des présentations techniques :-)