Reveal my Asciidoc

a deep dive into presentation-as-code

2020-01-09 - Benoit COUETIL

Introduction

Standard Asciidoctor capabilities are shown in this presentation.

The current presentation shows advanced Asciidoctor / Reveal.js capabilities, mostly helping going deeper in the everything-as-code devOps principle.

Guidelines for enriching the toolbox
  • Fewest non-generated images

  • Simplest source code

  • Fewest reveal.js or Asciidoctor fork (none so far)

Reveal.js plugins

The standard Asciidoctor / Reveal.js include the Zoom plugin with Alt+Click.

Some plugins have been added in the toolbox, see menu for shortcuts :

Chart-as-code

We enable chart-as-code with a modified version of chart-block-macro extension.

It’s based on C3JS, a layer on D3JS to draw charts easily, with nice mouseover animations.

Here are some examples.

Pie chart

What do you believe is the number one thing a compagny can do to improve code quality ?

Source

[chart,pie,order=null,legend=right]
....
Code Review,27
Unit Testing,19
Functional Testing,13
Continuous Integration,12
Integration Testing,9
Detailed Requirements,7
Static Analysis,3
Training/On-boarding,3
User Stories,2
Other,5
....

Bar chart

Source

[chart,bar]
....
data1, 30, 200, 100, 400, 150, 250
data2, 130, 100, 140, 200, 150, 50
data3, 130, -150, 200, 300, -200, 100
....

Horizontal bar chart

What are the main benefits of code review in 2018 ?

Source

[chart,bar,horizontal=true,x-type=category,data-labels=true,y-label="% answered"]
....
x, Improved software quality, Sharing knowledge across the team, Adherence to coding standards/conventions, Ability to mentor less experienced developers, Increased collaboration, Reduced project time/costs, Ability to comply with regulatory standards, Internal audits, Ability to set expectations, Enhanced customer satisfaction/retention, Enhanced mobility of code, Strengthen competitive advantage, ISO/Industry certifications
Interviewed developers using it,90,73,59,57,52,37,31,28,28,26,26,20,16
....

Combination

Multiple data types at once (using inline JS)

Source

++++
<div id="combi"></div>
<script type="text/javascript">
c3.generate({
  bindto: '#combi',
  size: { height: 500, width: 1000 },
  data: {
      columns: [
        ['data1', 30, 20, 50, 40, 60, 50],
        ['data2', 200, 130, 90, 240, 130, 220],
        ['data3', 300, 200, 160, 400, 250, 250],
        ['data4', 200, 130, 90, 240, 130, 220],
        ['data5', 130, 120, 150, 140, 160, 150],
        ['data6', 90, 70, 20, 50, 60, 120],
      ],
      type: 'bar',
      types: {
          data3: 'spline',
          data4: 'line',
          data6: 'area',
      },
      groups: [
          ['data1','data2']
      ]
  },
  color: {
    pattern: ['#B11E3E','#444444','#D6D6B1','#53A3DA','#8DBF44','#888888','#FFE119','#000075','#E8575C']
  }
});
</script>
++++

Diagram-as-code

All these architecture diagrams use PlantUML, with a custom skin to fit the theme.

Sequence diagram

rma sequence diagram

Source

[plantuml, rma-sequence-diagram, svg]
....
participant User
User -> A: DoWork
activate A
A -> B: << createRequest >>
activate B
B -> C: DoWork
activate C
C --> B: WorkDone
destroy C
B --> A: RequestCreated
deactivate B
A -> User: Done
deactivate A
....

Use case diagram

rma use case diagram

Source

[plantuml, rma-use-case-diagram, svg]
....
left to right direction

actor developer
database repo as "central\nrepo"
agent jenkins as "Jenkins"

rectangle admin as "Gerrit / Gitlab" {
    agent ui as "front"
    database repo_local as "local\nrepo"
}

developer --> ui : push
ui --> repo_local : push
ui -left-> jenkins: "\npush "
ui ..> repo : replication
....

Class diagram

rma class diagram

Source

[plantuml, rma-class-diagram, svg]
....
abstract class ArrayList {
  Object[] elementData
  size()
}
enum TimeUnit {
  DAYS
  HOURS
  MINUTES
}
Interface BaseClass

namespace net.dummy {
    .BaseClass <|-- Person
    Meeting o-- Person

    .BaseClass <|- Meeting
}
namespace net.foo {
  net.dummy.Person  <|- Person
  .BaseClass <|-- Person

  net.dummy.Meeting o-- Person
}
BaseClass <|-- net.unused.Person
....

Activity diagram

activity diagram

Source

[plantuml, activity-diagram, svg]
....
(*) --> "Initialization"

if "Some Test" then
  -->[true] "Some Activity"
  --> "Another activity"
  -right-> (*)
else
  ->[false] "Something else"
  -->[Ending process] (*)
endif
....

Component diagram

rma component diagram

Source

[plantuml, rma-component-diagram, svg]
....
package "Some Group" {
  HTTP - [First Component]
  [Another Component]
}
rectangle "Other Groups" {
  FTP - [Second Component]
  [First Component] --> FTP
}
cloud {
  [Example 1]
}
database "MySql" {
  folder "This is my folder" {
    [Folder 3]
  }
  frame "Foo" {
    [Frame 4]
  }
}
[Another Component] --> [Example 1]
[Example 1] -right-> [Folder 3]
[Folder 3] --> [Frame 4]
....

State diagram

rma state diagram

Source

[plantuml, rma-state-diagram, svg]
....
[*] -left-> State1
State1 -left-> State2 : Succeeded
State1 --> [*] : Aborted
State2 --> State3 : Succeeded
State2 --> [*] : Aborted
state State3 {
  state "Accumulate Enough Data\nLong State Name" as long1
  long1 : Just a test
  [*] --> long1
  long1 --> long1 : New Data
  long1 --> ProcessData : Enough Data
}
State3 --> State3 : Failed
State3 --> [*] : Succeeded
State3 --> [*] : Aborted
....

Work Breakdown Structure

wbs

Source

[plantuml, wbs, svg]
....
@startwbs
* Business Process Modelling WBS
** Launch the project
*** Stakeholder Research
*** Implementation Plan
** Design phase
*** AsIs Processes Completed
****< AsIs Processes Completed1
****> AsIs Processes Completed2
***< AsIs performance metrics
***< Identify Quick Wins
@endwbs
....

Timing diagram

timing

Source

[plantuml, timing, svg]
....
'skinparam backgroundColor white # does not work
robust "Web Browser" as WB
concise "Web User" as WU
WB is Initializing
WU is Absent
@WB
0 is idle
+200 is Processing
+100 is Waiting
WB@0 <-> @50 : {50 ms lag}
@WU
WU -> WB : URL
0 is Waiting #white
+500 is ok #white
@200 <-> @+150 : {150 ms}
....

Mind Map

mindmap

Source

[plantuml, mindmap, svg]
....
@startmindmap
* Debian
** Ubuntu
*** Linux Mint
*** Kubuntu
*** Lubuntu
*** KDE Neon
** LMDE
** SolydXK
** SteamOS
** Raspbian with a very long name
*** <s>Raspmbc</s> => OSMC
*** <s>Raspyfi</s> => Volumio
@endmindmap
....

Timeline-as-code

  • 1997 - Mondrian (Google)

  • 2002 - Codestriker (IBM)

  • 2003 - Rietveld (Google)

  • 2004 - Gerrit (Google, Android, Eclipse, OpenStack, GWT, IBM…​)

  • 2007 - Crucible (Atlassian)

  • 2007 - Phabricator (Facebook, AngularJS, Quora, Uber)

  • 2008 - Github

  • 2011 - Gitlab

  • 2012 - CodeFlow (Microsoft)

Source

[.timeline]
* *1997* - Mondrian (Google)
* *2002* - Codestriker (IBM)
* *2003* - Rietveld (Google)
* *2004* - Gerrit (Google, Android, Eclipse, OpenStack, GWT, IBM...)
* *2007* - Crucible (Atlassian)
* *2007* - Phabricator (Facebook, AngularJS, Quora, Uber)
* *2008* - Github
* *2011* - Gitlab
* *2012* - CodeFlow (Microsoft)

To reveal lines as fragments, use [%step] and put the [.timeline] before the title. See the result on next slide.

Skip fragments with PageDown / PageUp.

Timeline-as-code fragmented

  • 1997 - Mondrian (Google)

  • 2002 - Codestriker (IBM)

  • 2003 - Rietveld (Google)

  • 2004 - Gerrit (Google, Android, Eclipse, OpenStack, GWT, IBM…​)

  • 2007 - Crucible (Atlassian)

  • 2007 - Phabricator (Facebook, AngularJS, Quora, Uber)

  • 2008 - Github

  • 2011 - Gitlab

  • 2012 - CodeFlow (Microsoft)

Pyramid-as-code

  • Continuous deployment

  • Continuous reporting

  • Pre-commit pipeline

  • Continuous integration/testing

  • Design & architecture

  • Continuous improvement

  • Quality of work life

  • Organization and culture

Source

[.pyramid]
* Continuous deployment
* Continuous reporting
* Pre-commit pipeline
* Continuous integration/testing
* Design & architecture
* Continuous improvement
* Quality of work life
* Organization and culture

To reveal lines as fragments, use [%step] and put the [.pyramid] before the title. See the result on next slide.

You can skip fragments with PageDown / PageUp.

Pyramid-as-code fragmented

  • Continuous deployment

  • Continuous reporting

  • Pre-commit pipeline

  • Continuous integration/testing

  • Design & architecture

  • Continuous improvement

  • Quality of work life

  • Organization and culture

Screenshot-as-code

asciidoctorj screenshot
screenshot::http://www.gebish.org[asciidoctorj-screenshot,dimension=1600x800,width=600]

This uses the screenshot asciidoc plugin based on Geb.

Last slide

The last slide is there to open for questions.

We chose to have a slide with transparent background to reveal the background image.

[.questions]
=== !

[.bubbles]
=== !

[.hands]
=== !
They are appearing top to bottom here, this will be left to right on a standard presentation.
You don’t have to use one, but you will then loose the last section in the ToC, because it is always hidden for this purpose.

Word-cloud-as-code

Source

[cloud]
....
Continuous-Everything, Keep It Simple Stupid, Everything-As-Code, Don't Repeat Yourself, You build it You run it, Separation of concerns, Shift left, 80% of effects from 20% of causes, You Ain't Gonna Need It, Fail fast, What is measured improves, Culture Automation Lean Measurement Sharing, Value over cost
....
  • Words are on a single line

  • Words get smaller and smaller from 80% for the first to 20% for the last

  • Colors are picked in circle from a list

  • One word out of three is vertical

  • Outside of these rules, the layout is random

Word Cloud fragmented

Source

[cloud,fragment]
....
Continuous-Everything, Keep It Simple Stupid, Everything-As-Code, Don't Repeat Yourself, You build it You run it, Separation of concerns, Shift left, 80% of effects from 20% of causes, You Ain't Gonna Need It, Fail fast, What is measured improves, Culture Automation Lean Measurement Sharing, Value over cost
....
Skip fragments with PageDown / PageUp.

Positionning and sizing

Here are some positionning and sizing introduced specifically for Reveal.js slides.

[.halign-center]
You can center anything horizontally.

[.bottom]
You can put anything at the bottom.

You can center anything horizontally.

You can put anything at the bottom.

Text wrapping near image

one ring

Three Rings for the Elven-kings under the sky,

Seven for the Dwarf-lords in their halls of stone,

Nine for Mortal Men doomed to die,

One for the Dark Lord on his dark throne

one ring

In the Land of Mordor where the Shadows lie.

One Ring one ring to rule them all, One Ring one ring to find them,

One Ring one ring to bring them all and in the darkness bind them

In the Land of Mordor where the Shadows lie.

Source

image::one-ring.jpg[width=300,float=left] (1)

Three Rings for the Elven-kings under the sky,

Seven for the Dwarf-lords in their halls of stone,

Nine for Mortal Men doomed to die,

One for the Dark Lord on his dark throne

image::one-ring.jpg[width=450,float=right] (2)

In the Land of Mordor where the Shadows lie.

[.green] (3)
*One Ring image:one-ring.jpg[width=40] to rule them all, One Ring image:one-ring.jpg[width=40] to find them,*

[.green] (3)
*One Ring image:one-ring.jpg[width=40] to bring them all and in the darkness bind them*

In the Land of Mordor where the Shadows lie.
1:: block image float left
2:: block image float right
3: inline images

Maxed-out image

sunset

Source

Whatever the image size is, it will cover space without changing the ratio.

[.maxed-image]
image::sunset.jpg[]

Big image

sunset

[.big-image] is the same as [.maxed-image] but gives some space for text.

[.big-image]
image::sunset.jpg[]