If you monitor my Twitter feed, you might have noticed that I was sent a free copy of a Instant Markdown eBook from Packt Publishing to review. I’d not come across Packt before but their general approach looks good - making DRM-free eBooks in multiple formats (once bought, you can get the ePub, PDF or Kindle versions) and paying some kind of royalty to Open Source projects that form the basis of their books. Despite time being a bit limited at present, learning more Markdown is potentially a big timesaver (as I use it a lot now) and it’s a short book, so I agreed.
Unfortunately, the book itself turned out to be rather disappointing. It was indeed quite short - a bit too short. The topics covered were themselves quite useful and it reminded me of a couple of things that I had previously noted to look up. The problem was that they did not really provide any insight that five minutes on Google or, in some cases, even the Markdown Wikipedia article would not match or beat. All too frequently, the content consisted of:
- XXX: Read about it at
<url>.
Screenshots, examples and even descriptions were sorely lacking. Just directing the reader to a website does not really seem enough to me. It’s the kind of thing I might do it my blog, or in a Markdown cribsheet, but not in a book, even an e-Book - especially one priced at £7.64. (Bizarrely, when there are screenshots they tend to be things like login screens, which is rather pointless.)
The lack of screenshots in the intro section could be forgiven as one of the best ways to learn Markdown is just to play with it and see for yourself what it does. Another criticism that I have, however, is that this eBook does not explicitly promote this approach: rather than starting with an online Markdown editor, such as Markable (or one of the other editors mentioned later in the book), the author begins by recommending the download of the official Markdown Perlscript and running it from the command prompt as a starting point.
The other reason that a different approach would be useful is that the book seems to assume a lot of HTML knowledge from the outset. Being a bit of a geek, I generally code my webpages in raw HTML - or, at least, I did before I discovered Markdown! - and so I recognised the HTML code that the Markdown was being converted into. People used to WYSIWYG editors might not be so familiar, especially with tags like <blockquote> and <code>. I am not sure at whom the book is aimed but it seems too superficial for geeks and yet too geeky for non-geeks.
Some of the more advanced features in the Top 8 features section are potentially useful but suffer from the superficial handling mentioned above. A few more screenshots or descriptions would have been useful for tools such as Scriptogr.am and writing Presentations - what do these things look like? Ditto the MultiMarkdown section. For example, the maths section for this is:
Math
Here is a math support example:
\\[ {e}^{i\pi }+1=0 \\]
I don’t know about you but, at the very least, I would like to know what \\[ {e}^{i\pi }+1=0 \\] actually looks like when converted into HTML and opened in a web browser. For me, this really epitomises the book: it feels like it was lazily knocked out in an afternoon.
There were some useful things here - Pandoc is something I will be playing with and it was good to be reminded of it - but I’m not convinced that it is any more useful that one of the many Markdown guides that are kicking around for free online. (Some of these, almost ironically, are provided in “People and places you should get to know” section!)
The final problem that I had with this book was the lack of critical insight. It will, for example, give the basic code for embedding a picture in Markdown but fail to point out that it cannot be sized or aligned - to do this, you need to insert actual HTML. It will point to a few different tools but not really discuss the pros and cons of using an online versus local editor, for example. When giving the code for inline links ([text](url)) versus reference links ([text][ref] … [ref]: url), I expected it to point out that the former was clearer and safer if likely to be combining Markdown text from different sources (especially if using numerical references) whereas the latter is better if the same URL is being referenced multiple times. There was nothing like this. As someone who has largely picked up Markdown on the fly, I had hoped to pick up some useful tricks and tips and things to watch out for. I did not.
In summary, this is a handy reference guide to Markdown with some links out to some useful tools that themselves use Markdown. At £7.64, however, this eBook is not worth the money. More informative guides are freely available just a quick Google search away. (The documentation of free Markdown editors like Mou (Mac OSX) and MarkdownPad (Windows) is a good place to start for the curious.)
