Thursday, 6 October 2016

A Case Study in Creating a Conference Presentation using Markdown

TLDR; using Marp and Pandoc I can write a report and presentation using Markdown, then add other tools to make it 'pretty'.

I’m going to show you a case study in how I’m planning a presentation for conference.

Because I want to offer you an alternative to diving straight into a powerpoint presentation.

My process for creating slides

What I’ve been doing is:
  • create an evernote
  • make all my notes in there
  • rough out some of the notes as summary info to add to a slide
  • create rough slides
  • expand my notes so they are like a ‘paper’ to support the presentation
Then I’ll:
  • move on to the slides
  • tidy up the slides
  • practice the presentation
  • keep the ‘paper’ up to date
And all of this means jumping between a few tools and I don’t really like working with presentation tools.

I’ve been looking for an alternative that fits my workflow.

An alternative that fits my workflow

And I think I might have found it. And I can:
  • write everything in markdown
  • version control my text
  • keep the ‘slides’ and the ‘paper’ together in the same file
  • create a pdf of the paper - with ‘embedded slides’ - without doing any exporting or editing
  • create a pdf of the slides - without any extra editing or maintenance
And now I think I’ve found a way of doing that - and of creating ‘nicely formatted and professional slides as well’ - all without touching a presentation tool.

So let’s have a look.

The Making Notes Phase

I’m still in the making notes phase for this presentation. This example is my presentation for TestBash Netherlands in January 2017. (official Test Bash site)

I make notes on it and restructure it when I get an idea - sometimes that means waking up at 3 in the morning and sitting in the office to type up the ideas, but that’s how I work on presentations.

In my earlier workflow, I would just have a set of notes at this point. And I would create those by running my ‘notes’ through pandoc to create a pdf.

With my new workflow. I already have:
  • a set of notes in Evernote
  • a pdf of the paper generated by Pandoc
  • a presentation (using Marp)
I could wing it tomorrow, if I had to.

This is a massive win.

I always like to be at the point that ‘I could do it tomorrow, if I had to’. But I’m never usually at that point so early in the preparation cycle.

What that means is that every iteration from now on is an improvement (hopefully).

I could wing it tomorrow!

So I have notes, and they look a bit like this:

---

# And I'm going to say that:

## "any software that I use to support my testing is a "Testing Tool"


<!--

So if I use Cucumber in my testing it becomes a "Testing Tool"

And you can argue about it all you want. It won't stop me using it, or misusing it (if you say its not a testing tool and I use it in my testing).

-->

---

And when I say “they look a bit like this”, I mean “they look exactly like that”.

I copy and pasted the above from my notes.

And what you can see is:
  • a draft slide
  • slides a separated by ---
  • and my ‘paper’ inside the HTML comments
I would normally continue working like this, in Evernote and a text editor. Until it was time to create the slides.

I can create slides now!

By using Marp, I can save my notes to a text file.

The same text file that I would feed into pandoc.

And I can view my notes as a set of slides.

The reason I use <!-- and --> to delineate my ‘paper’ sections is because most Markdown processing tools ignore HTML comments.

Marp, ignores HTML comments and only displays the --- delineated parts as a set of slides.



Using Marp, I can:
  • view my notes as a set of slides
  • get a feel for my notes as a ‘presentation’
  • output a pdf that I could use to ‘wing it tomorrow’
The Marp slides output isn’t great, but it is certainly ‘good enough’, and I released the Java and Selenium Install Checklists to slideshare using Marp, directly from the checklist file that I maintain on github:
Same source document different rendering.

The PDF isn’t ‘perfect’ but its good enough for my purposes.

I can view the paper easily!

If I copy and paste the contents of the file or evernote into dillinger.io

I can see a rough version of the paper, but Dillinger shows me the <!-- and --> which isn’t great, but for review purposes this is fine and easy.

I couldn’t use Dillinger to release the paper in that condition though.

I can create a pdf paper easily!

I use pandoc to create PDFs.
If you’ve hired me for consultancy work - pretty much guaranteed that the PDF report you received at the end was generated in pandoc.
Trade Secret - I can create a report really quickly because:
  • I write it as I consult
  • When I make my notes in Evernote
  • I write in Markdown
  • I convert with Pandoc
  • I spend time at the end of the day (/trip back on the plane/journey back on the train/engagement in the airport lounge) editing and fixing spelling errors
  • generate in Pandoc - I tend not to spend much time reformatting
Shh, keep that a secret though, I don’t want my competitors to have the same advantages that I have.
Normally I just run a text file through pandoc:

pandoc mynotes.txt -f markdown -o professional_report.pdf

(pandoc can change page size and create a table of contents and output MS Word and OpenOffice files, but somethings I’ll keep as trade secrets.)

But pandoc would ignore the HTML comments as well, so I create a script:

(Get-Content slides.txt) | ForEach-Object { $_ -replace "<!--" , "-----" } | 
ForEach-Object { $_ -replace "-->","------" } | Set-Content slides.md
pandoc slides.md -f markdown -o output.pdf

Above is windows powershell which converts the HTML comments into Markdown horizontal rules.

I converted an open comment <!-- to five minus signs -----and close --> to six ------ to give me the option of ‘find and replacing’ the report back into a slide deck if I want to.

If I was on mac I’d probably create a .sh that used sed to perform the find and replace operation.

This gives me a fairly nicely formatted pdf.



Good enough.

It makes it easy for me to see:
  • where I have a lot of content,
  • where I have less
  • what is a quick slide
  • what is a slow slide
  • what is summary
  • what is detail
  • etc.

And the main point for me is that I get this with no extra effort.

I can imagine that to release the paper I would convert the comments to "" and avoid having extra horizontal lines.



But for the moment, I’m comfortable with the double lines, and the removal of comments is a one way operation.

Version control benefits

A great benefit from this is that the only things I need to version control now are:
  • a single text file
  • a conversion script
  • any images
I don’t need to add
  • a huge LibreOffice or Powerpoint presentation
And I have proper versioning so:
  • I can diff the notes and slides,
  • I can bring back lost information

But it ain’t that pretty at all

I’m not that bothered about the ‘prettyness’.

Normally I ‘prettify’ the slides close to the release date anyway.

But we can automate it all!

I’m currently evaluating Deckset.

A Mac only app which can take my ‘notes’ file with the slides and the HTML embedded ‘paper’ and can format it into something ‘pretty’:



I ‘just’ have to:
  • choose a template
  • pick the colours
  • then ‘tweak’ the Markdown to make it work better as a slide deck

Next Year…

I guess we’ll see in January 2017 how I actually create the slides.

And we’ll see which of the above slides actually make it from the ‘Notes’ phase, into the ‘Finalise Slidedeck’ phase.

Tools Mentioned
Bonus video showing the tools in action (available on youtube)


No comments:

Post a Comment