How to write a Ruby-related book - the tools

I have recently published the 1.0 release of the "Rails Refactoring: Rails Controllers" book. It took me over 1 year since I started. Over the time, I've experimented with many tools which helped me along the way.

This post is a summary of some of the tools.

The short version

iaWriter for the initial writing
vim/sublime for editing
LeanPub for PDF/epub/mobi generation
Github for storing the source files (markdown)
DPD for selling
MailChimp for email list
Trello for task management

The longer version

After I knew what to write about (the process how I came up with the "idea" is another topic - let me know if you're interested in reading about it) - I've had a bunch of notes, scattered across many tools - Evernote, Hackpad, MindNode, code repositories.

Despite all the temptations, I didn't try to find the best tool for writing. I know myself and that would result in endless experiments without any delivery. Obviously, there was a temptation to write such tools on my own. I'm very happy I didn't go this way.

The minimal requirements was to have a tool that generates a PDF.

Kitabu

The first tool that seemed to be good enough was  kitabu. It was a good tool - think Rails but for books, a whole framework.
They even give you the familiar "$ kitabu new mybook" tool.

Kitabu was a very programmer-friendly approach.

I eventually gave up on Kitabu. The problem was with the commercial PDF tool (PrinceXML) which is used by default. I was OK with paying for good software, but at that time, the license was about $2,000 which was a bit too high.

Scrivener

Then I switched to Scrivener. I loved this tool. I found it through some "real" writers forum. It's very popular among writers. It's a desktop app. It's great for notes collection, structuring, drafting. It's good at WYSIWYG. It has a built-in PDF generation. It supports export/import from markdown.

At some point, more people from my team started to help mi with the book. The Scrivener approach wasn't very team-friendly (or I wasn't able to use it). No easy way of two-way sync with markdown. Other people would have to be forced to use Scrivener as well. Also, it wasn't very version-control-friendly.

Leanpub

Meanwhile, Robert Pankowecki (with a little bit of my help) was working on the Developers Oriented Project Management book. He used Leanpub and this tool was very team-friendly. There was a repo, we could all contribute into. It generates PDF/mobi/epub (on their servers) via a Github hook.

The Github repo:

(as you see there were 300 commits so far and 13 people contributed to the book!)

I was sceptical at first, as they (at least at that time) didn't give emails from the book readers. I found it very limiting for marketing/sales activities. However, LeanPub lets you generate the PDF and take the files with you to sell somewhere else. That sounded perfect to us.
Over the last year, I've seen how Leanpub (the UI) keeps getting better. I may seriously consider switching to them as the selling tool as well at some point. They now also have an iOS app for reading your books.
So far, we're staying with Leanpub for our books (the third one is in progress).

My book is very code-heavy. LeanPub is great for it. They not only support syntax highlighting but they also let us present nicely the diff between two pieces of code.

One minor issue with Leanpub is that you need to wait for the PDF generation (30-60 seconds). I usually work locally, do frequent commits to the local repo. Every now and then I push to the github repo. This triggers a hook, which notifies Leanpub. After a while, I launch a simple bash script  - download_and_preview.sh - which downloads the newest PDF and opens Preview on my Mac (if it's already open then it reloads the file). This is a good-enough flow.

iaWriter

Leanpub lets me write in MarkDown. For some time, I've used vim for that. After a while, I realized that there are two aspects of writing. When I write the initial version of a chapter I need a full focus to let the flow work. iaWriter is a perfect tool for distraction-free writing, with a beautiful full-screen mode. This is where I do most of my initial writing.

When the draft of the chapter is ready, I need to do more editing (it's like refactoring but for normal text). This is when I usually launch either vim or sublime. The vim shortcuts lets me do editing faster.

When I'm done and ready for a new release of the book, I run the 'release' script:

This created a capistrano-like directory and creates a new .zip file.

DPD

I use the DPD system for selling. Unfortunately, they don't have the API to automatically upload a new .zip file and manually change the product configuration. I hate this part, as it's very error-prone. I even attached the wrong file to the wrong product once.

As for payments, DPD only supports PayPal (at least for a Polish company, last time we checked), so this is what I went with. I'm not a big fan of PayPal, but it didn't seem to be a huge problem for all the buyers.

Whenever I have a new release, I can send an email from the DPD panel to all the customers, which automatically generates the appropriate download URL.

As you may expect, DPD gives you all the reporting, charts, data which you may need.

Slack

Over the time, we've created notifications around the whole process. Whenever a new commit is pushed into the repo, a new notification appears on a special Slack channel. Whenever a new sale is made, we have a SalesPanda bot which notifies us about it to the same channel.

Summary

As you see, the whole process is a combination of multiple tools. In some places, they are integrated automatically, while some places are still manually updated. The perfect setup would be to have a Continuous Delivery and we're very close to such thing here. When the delivery is a PDF, the problem is that you would need to email people on every Delivery. This doesn't sound perfect, though. With this book, I think I've had 4 releases so far and this worked well - starting from February 2014 until now.

Feel free to email me at andrzejkrzywda@gmail.com if you need any help with writing a book. It might be overwhelming at first.

The landing page (pure html/css) of the book mentioned in this post is here: http://rails-refactoring.com