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

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
pandoc -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)

Thursday, 29 September 2016

Adhoc testing of incrementally developed HTML and CSS

TLDR; Even simple changes can use step by step risk based development to allow multiple releases, and will require multiple levels of testing.

My website is in a constant state of flux - that’s the benefit of writing it all by hand.

Today I wanted to add nifty social media icons on the page because I hear tales that there is gold to be made from the contacts that come from such things. And never one to turn my back on boundless riches, I wanted to add some social media and contact icons.

And why tell you this?

  • the testing process around this has relevance
  • I learned something about CSS and I assume other people might like to learn that too

Monday, 26 September 2016

How to Use Chrome Developer Tools JavaScript Source Snippets

TLDR; With Chrome Code Snippets we can ‘run’ small chunks of code without using the console. And using a gist we can import and export them to a file.

We already know that we can run custom JavaScript code from the console. I explained that in this blog post.
And we can use Google Chrome Code snippets to re-use that code over time.
By default we can’t import and export, but people have written helpful code to let us do that as well.

Friday, 23 September 2016

How to use the JavaScript Console for Technical Web Testing

TLDR; learn how to use the dev console and basic JavaScript commands (for, do…while, if…then, variables) to automate under the GUI and augment your interactive technical web testing.

I used to only use the JavaScript console in the Chrome Dev tools was for viewing JavaScript errors.
But I read the documentation for the JavaScript console
And realised that I could issue commands and view objects. And I slowly came to realise that I could use this to help me test better.

Thursday, 22 September 2016

How to Treat your Application as an API - "App as API"

TLDR; Look at what your GUI does. Automate that. And you’ve implemented “APP as API”

A phrase I’ve found myself using in various training sessions is “App as API”.

I think I’ve mentioned that in some previous blog posts but want to expand the concept here.
  • Some applications provide an API
  • Most applications provide a GUI
When the application provides an API, I like to take advantage of that. But…
  • Sometimes the API doesn’t do everything I want.
  • Sometimes the functionality I want to use is only available from the GUI
Do I let that stop me?


So what do I do?

Wednesday, 21 September 2016

How to write a simple random test data sentence generator

TLDR; I wrote a random test data generator, not a slogan generator

On the Importance of Test Data

We all know that test data is really really important.

If you don’t have the right data, you can’t test the functionality. You can’t check that an email is sent out on the customer’s 65th Birthday unless you have a customer who has a date of birth that will trigger that functionality.

Some data is path invariant and has to be specific to control the path.

We know this.

But we don’t always randomise enough data and our test data becomes stale and etc. etc.

Monday, 19 September 2016

Difference between hacking, cheating and automating?

TLDR; Hack for information. Cheating breaks the rules and introduces more risk. Automate the interfaces with less risk.

Previously on "Evil Tester goes Hacking JavaScript Games" I demonstrated a ‘bot’ that could play ZType

My bot cheated and automated shooting, I hacked

The bot has been through a few iterations:
  • 0 - every few seconds it uses an electro magnetic pulse and then gives itself a new emp, therefore having infinite emp devices
  • 1- every 100 milliseconds it iterates through the letters available and shoots that letter watch bot 1 beat a human
  • 2- fixes a bug in (1) so that it only shoots letters which are used on the level
  • 3- once it knows what word is currently being shot at, it uses the letters in that word, but when it doesn’t know the word it shoots all the letters on the level
  • 4 - only shoots letters on screen, every 10 milliseconds, either the start of a word then continues on the word
  • 5 - only shoots letters on screen, which are the start of a word, then focusses on that word to shoot it to bits (doesn’t wait 10 milliseconds to finish the word) - 100% efficiency
  • 6 - essentially bot 5, but only waits 2 milliseconds watch bot 6 in action
The different versions represent ‘cheating’ or ‘automating’.
I had to ‘hack’ to get the information I needed to ‘cheat’ with bot zero.