The Write Tool for the Job

Lately, I’ve been working on a lot of documentation projects. That includes building up a manual for TruckingOffice ,and documenting the development process we use at nMany.

I’ve worked on large documents in the past in both Word and OpenOffice. You could write them, but they quickly became unwieldy. I switched over to LyX because it made it so much easier to build large structured documents.

Since it had been a while, I thought I would look around at the tools available. I’ve read a lot about self publishing. I downloaded a bunch of kindle samples on the subject (including APE which I recommend).

I tend to look for technologies that work well across platforms, since although I’m on Linux most of my co-workers run Macs. I’m generally obsessed with the safety provided by source code control in general (and git in specific) so I wanted something that would work with that as well. Being able to diff things and merge conflicts between writers would be a nice bonus (but that eliminates most binary formats).

A lot of the things I wanted where shaped by meeting the Pragmatic Programmers team a while ago. At the time they were working on a proprietary system to make it easy to auto generate books from xml/text so that they could source code control it and quickly generate new versions as bugs where found.

As I looked around, I went back to ebooks I’ve read lately. Several months ago I bought a book on Sublime Text because I wanted to evaluate it to see if I should give up RubyMine. In the process of researching more self publishing (since a lot of tools are being built for that market), I ran into an article by the guy who wrote the Sublime Text book. His article How I made $2,000 in 7 days launching my ebook pointed me at LeanPub as a cool platform.

Looking into it, I quickly fell in love. They handle writing documents in plain text with markdown. Their markdown has some improvements to give you features you need for a book (like call outs and sections). Since I can write chapters as seperate text files it is super easy to manage in git. They share a DropBox folder which is where you put content you want to publish.

The other thing that is great is the way you include code and images. You get to make references to external files for both of them. That means that I can leave code in a directory where I can run and test it, and whenever the book is generated I know that it will grab the latest version. The same thing for images. That means when I make a change I don’t have to fix, find, copy, and paste. I just edit the file in place and everything will just update.

They also handle generating the book in pdf, kindle, and mobile versions which is one less thing to think about.

I had a problem where the text file I generated had some kind of strange UTF-8 character at the beginning of each file. This cause the rendering of my book to go crazy. I sent them an email, and the next day they rolled out code that handled the problem.

When you combine the LeanPub platform with FocusWriter, it is amazing how much I get to focus on the writing part of the show. This is becoming my default stack for writing large documents.

 

p.s. I have one other writing project I’m hoping to announce shortly so stay tuned!