Faster Presentations, kill kill kill it

Bang out killer presentations in minutes.

I am now in a position where I am asking others to present their ideas to a group. I want to make it easy for them.

It has been my experience that people who have interesting things to present, usually don't have a lot of time to prepare their presentations. They face the serious trade off of time versus quality. They must resist the temptation to spend hours adjusting colours and their other graphical elements in ways that feed an internal pathology more than it will serve their audience.

Here is a personal example: I just spent the last 20 minutes looking for "time wasting pictures", to make my point and this was the best I could come up with.1

Could you focus on the words of my presentation? I couldn't, what a waste of time.

If the presentation is technical, requiring mathematical notation, more time is killed fighting with your crappy \LaTeX distribution or whatever other typesetting garbage you are using. In so many ways our technology gets in the way.

This time wasting makes complete sense to me, since standing in front of a crowd has a direct impact on reputation. Everyone is watching you, so you want to look good, sound good and you want your slides to be amazing.

How about this instead, make your slides good enough. Save your time for what you really care about, honing your message, simplifying your metaphors... making your ideas sticky.2 This requires real mental work and the presentation technology will probably just get in your way.

Enter, madoko.

It's free, it's fast and it's, .. well, it's good enough. You can bang out a presentation in minutes. You write your presentation in markdown, which is a very simple markup language that has won on the Internet. Markdown is expressive enough to write your presentation, but not expressive enough for you to waste a lot of time tweaking it.

To see an example of madoko, go to Daan Leijen's madoko page. On it you will see an example of how to use it, and interactive page for adjusting the presentation and a lot of promises about how you can just link to drop box and run your presentations live from their servers.

I believed their dropbox promises, then when I was standing in front of a group ready to present, their technology fell over. I learned my lesson, don't trust anyone, ever!

If you are going to use madoko, go and get it, then run your files through it locally on your machine. When I tried to do this, it failed out of the box, with a very unhelpful message.

return binding.rename(pathModule._makeLong(oldPath),

You get what you pay for.

After really digging in (by googling the error message), I found that someone who pioneered the problem found that you can get around it by adding a -pgn switch.

So, instead of

> madoko -v document.mdk (breaks)

Do this instead:

> madoko -v --pgn document.mdk

The only downside of this second command is that you generate pgn files instead of svg files. Who cares.

Now, I will provide a simple set of ideas and instructions so that you can install this technology on your system, use the madoko page to work on your presentation with live updates, then render your work onto your local machine so that your pants stay on while you present in front of very important people.

  1. Madoko needs node. Node is a programming language. If this worries you, relax. You don't have to know how to program it, you just install it so that madoko can use it to make your presentations. Download and Install node

  2. When you installed node, it installed a package manager onto your system that will let you get programs written in node, from a place that hosts a whole bunch of free programs. A package manager makes it easy to get programs. It also makes it easy to get rid of them when you don't want them anymore. You can use the node package manager, npm, from your command line to get madoko and install it so that you can access it from within any directory on your computer. Open the cmd prompt, or your shell and type:

    > npm install madoko -g
  3. When this command is completed, you will be able to access madoko from your cmd prompt or your shell. Try it now, it should spit out a help message:

    > madoko
     madoko [options] files
                  --version          Display version information
     -v           --verbose          Be more verbose
                  --odir=DIR         Write output files to the specified directory
                  --xmp              Only process markdown between <xmp> tags
                  --tex              Generate a LaTeX file too
                  --pdf              Generate PDF using LaTeX
                  --texzip           Generate TeX zip for submission
                  --png              Use PNG instead of SVG for math in HTML
                  --convert-tex      Convert input from TeX to Markdown
     -f           --fragment         Generate a fragment instead of a full document
                  --logo             Generate a logo at the end of the document
                  --sanitize         Always escape or suppress user defined html
                  --sandbox          Run in a sandbox for secure server execution
                  --pedantic         Pedantic mode
                  --bench            For benchmarking: turn off numbering, etc.
                  --installdir=DIR   Set installation directory explicitly
     -r           --rebuild          Force rebuild bibliography, math, etc.
                  --prelude=FILE     Include <FILE> at start of the document
                  --verbose-max=LEN  Maximum line length for messages
     -m<key:val>  --meta=key:val     Semi-colon separated list of metadata values 
  4. Now go and get some example files from the madoko site, copy the text contents into a local file called document.mdk. The "mdk" extension just tells you that it is written in markdown.

  5. In the directory that you copied the document.mdk file into, create a directory called images. Then copy the butterfly.pgn3 and arrow.pgn4 images below and put it into the 'images' directory.

  6. In the same directory that you put your 'document.mdk' file run madoko. This will generate a presentation that can be viewed with your web browser.

    > madoko -v --pgn document.mdk
  7. This last command will create a new directory, called "out" full of mostly \LaTeX garbage. The file in this directory that you are interested in is called document.html. Open the document.html file in your browser and you should have the presentation working on your computer.

That's it. You now have a place to start. If you want to change his presentation and make it your own, which you do, go to the interactive madoko site, make your changes and see the presentation updates live. His presentation is beautiful in that it explains the presentation technology itself. Play with his file and make it do what you want it to do. It will update live in your browser. This will reduce your development feedback cycle.

When you are happy with the results, copy your text back into your own document.mdk and rebuild the .html file with the instructions in step 6.

Your generated document.html file will work without an internet connection. Rename it to something useful to you. You don't need dropbox, you don't need azure or any other crappy technology that might fail when it's go time. You can use them if you like though, it's nice to have options.

I followed my own little tutorial and then mapped the resulting presentation to the server that is hosting this blog, you can see it here. Over time I will place all of my presentations there.

Madoko is very cool, you can use it to also generate pdf files, and you can generate some pretty advanced output if you care to. To see it's advanced topics, check out their doc section.

Here are some example presentations I made for a business-plan-slam:

  1. What kind of pathology do I have?

  2. Or whatever you actually care about.