Lessons from self-publishing - Part II

So now the book is done and dusted I wanted to discuss how I wrote it and what tools I used.

The book was written in a mix of Markdown with some LaTeX for indexing, formatting and figure placement. The actual writing was done mostly in iA Writer and Vim. I love iA Writer as an interface. It’s clean, simple and has a focus on your putting words down on paper rather than having 10,000 options and functions and menu bars. It’s like the anti-Word and I can’t praise the team there enough (they are also awesomely responsive to questions and problems).

For the production I looked around a lot for options that would support a good design and outputs in multiple formats. After some testing I decided my old friend Pandoc was the way to go. It supports converting from Markdown to LaTeX and to PDF. It also supports using a LaTeX template for conversions that allows your final product to be incredibly flexible. Also John MacFarlane is incredibly helpful when you have issues. I needed to ensure my code blocks didn’t get split across pages and he took the time to help identify the problem and then wrote a Pandoc plugin for me to fix my issues. That’s how you run an open source project. I also don’t know when he sleeps given he has a full-time job in addition to Pandoc.

To make the compilation process for LaTeX faster and a bit more elegant I also added in Rubber which is a build system for LaTeX that ensures a LaTeX or PDF document is compiled the right number of times for references to be generated and other niceties.

It did take me a little while to re-learn LaTeX and I am sure some of my template is seriously hacky in places. The final product, however, looks awesome.

I was assisted in the production process by the team from Backbone.js on Rails allowing me to use the simple Rake-based wrapper they developed to produce their book. I hacked it up considerably to achieve my ends but having it as a starting point saved me the hassle of producing one myself. At some point, you know when I am not busy and all, I intend to hack it into an actual customisation platform so I can create book skeletons quickly and easily.

Finally, everything was version-controlled and stored in Git on GitHub. It may seem weird to version control a book but I think it’s actually the ideal platform for this especially if you’re writing in a non-binary format and can see diffs.

Overall, it’s important to remember that a builder cares for their tools but doesn’t obsess over them. I spent a fair bit of time tweaking specific format and display issues and made a small investment in streamlining my production process. I didn’t, however, lose sight of the fact that I was writing a book and that means putting (good) words on paper.