How I Write Books about Python

I get asked questions about my book writing process from time to time and I have been meaning to write about this topic for a while. The main reason I wrote my first book, Python 101, was because of the readers on my blog. They had been encouraging me to write a book on wxPython for a while and I decided that I should start by writing an introductory book so I wouldn’t need to include a bunch of introductory information in my intermediate level book if I ever got around to writing it.

When I was writing that book, I had to search for ways to generate PDF, mobi (Kindle) and epub formats. I skipped Microsoft Word because I hadn’t seen good ways to convert that document type to other file types and it didn’t work well cross-platform anyway.

The Toolchain

I ended up going with RestructuredText. I did try Sphinx as well, but couldn’t get it to work the way I wanted in the timeframe I had given myself. However RestructuredText allowed me to convert to PDF easily with rst2pdf.

Then I used rst2html to create an HTML version of the book. When you have HTML, you can then use Calibre, a book conversion utility, to convert to mobi and epub formats. When I ended up with was a Python script that would call rst2pdf, rst2html and Calibre to convert my book into the appropriate formats.

This worked pretty well, but didn’t create a very good Table of Contents.

When I was working on Python 101’s sequel, Python 201: Intermediate Python, I discovered Leanpub, which uses Markdown for their books and will take that format and convert it to all the output formats I wanted. the output looked nice and best of all, it had a proper Table of Contents.

So my current toolchain (as of early 2019) is now to write in RestructuredText and use Pandoc to convert it to Markdown. I do it this way to make it easier to switch back to my home-brewed book making scripts in case I decide to drop Leanpub for some reason. Frankly what I would like to do is create a script using ReportLab that can take Markdown or RestructuredText and turn it into a PDF. I suspect I could get something of equal quality going that route, at least for PDFs.

2020 Update: I ended up dropping RestructuredText and switching to Markdown because I discovered that Pandoc wasn’t converting code examples and other special structures correctly. This caused syntax highlighting to not work correctly.

Research and Development

When it comes to choosing topics for my books, I usually use what I know is popular on my blog. For Python 101, it was a little different in that I had read many beginner books on Python and decided I wanted to cover a lot of topics that I didn’t see covered in beginner books very often. One example of that was showing how to publish your code to PyPI or create an executable with Python.

I keep an eye on my blog’s statistics to know which articles are doing well as that gives me ideas for content of books too. The two reasons for creating my book on ReportLab was that

There were no books on the topic and
Articles on ReportLab tended to be in my top 10

Kickstarter also comes into play a bit here in that I ask my backers what they think should be in the book and then I take those ideas and rank them and decide which ones will make it and which ones will not.

Reviewing the Book

Being a self-published author, I run a pretty tight ship. I don’t have a publisher to pay people to review my works, so I have to be creative. I ended up using my blog as a beta testing site in some ways. I usually post new chapters from my books on my blog to get feedback from readers passively. I also believe in making my books mostly open source, so posting the chapters there is nice for my readership and for me when I need to look something up.

I also use Kickstarter for some minor beta testing. There are usually backers who want to read the book early and they give me a lot of feedback as well. This has been quite helpful and the books have ended up a lot better because of it.

I have worked with two publishers at this point and neither of them have given me the kind of support and feedback that my readers have. I am grateful for all of you.

Getting Feedback From Readers

Speaking of feedback, I get my feedback mostly through Kickstarter and from comments on my blog. All of my books have email addresses that the reader may use to send me an email as well. I do get a fair number of emails from readers using that method, but I think I get more from the first two sources I mentioned.

Most feedback is positive and really encourages me to continue writing. I occasionally get some grumpy mail, but even those rare cases have been helpful in seeing what I could be doing better.

Updating Your Book

When you choose to write about tech or computer science, you know your book will become obsolete over time. One of the best things about self-publishing is that I can take feedback and fix a book in a matter of hours or days and push those updates straight to the end reader. I have fixed bugs and pushed out new versions of the book with hours of receiving a bug report.

I do updates for books for several different reasons:

The book is now out-of-date
The book has a typo
The book is wrong (dang it!)

I try to write about topics that won’t change for a while. For example, wxPython and ReportLab don’t change very often in breaking ways. So I can write about them without needing to worry that my examples will be broken when the book is released. Python itself is also that way, for the most part. However Python has changed more than I expected it to since 3.5, so I do need to rewrite Python 101 to account for those differences.

Selling Your Book

My original thought when it came to selling books was to just post it on my blog and see what happened. Then I realized I could use Kickstarter to gauge interest in my ideas, so I decided to do that instead. Kickstarter is great for this. It really helped me connect with my readers and keep the feedback loop small with the early adopters.

Kickstarter has also been good for updating readers when it comes to updates to the books as well as for my future works. Note that Kickstarter does take 8-10% of the total, so if you do decide to use it, you will need to keep that in mind.

I have read that if you advertise, you should use no more than around 5% of your gross for it. I haven’t tried this very much as my experiences with online advertising hasn’t been very good.

Now that I have multiple books, I can take them and bundle them together in different ways. Leanpub also supports bundling your book with other books on their platform from other authors, if you can find some that want to do that with you.

I recently started doing Youtube videos which I think has helped raise awareness of my blog a bit, but not a lot. Youtube is a very different medium and really doesn’t drive a lot of traffic at the moment, but I think it could if it was leveraged correctly.

You can use Gumroad to sell your books as well. They have an affiliate program that you can use if you can find affiliates. I have been experimenting with that a bit and it seems to work pretty well. Leanpub discontinued affiliates, which is unfortunate.

Keeping in Touch with Readers

Keeping in touch with your readers is difficult. Depending on your selling platform, you might not be able to. For example, Amazon and Leanpub do not share buyer information at all. A reader can opt-in on Leanpub to receive updates but I cannot see any of their information. Gumroad does give the seller an email address, so you can use that to build a mailing list. Just make sure that you remove anyone who isn’t interested.

As I mentioned, Kickstarter is useful for this. I can send out updates through their website to all my backers. I also get email addresses from them for delivering the eBooks. Technically you could build a mailing list this way too.

I should note that I have not done this. I only use the email addresses to deliver their goods and then I won’t bother anyone again unless I need to.

Time Management

Before you set a deadline for a book, you should definitely outline as much of the book as you can. I have found that creating a list of the chapters I want to cover helps me keep the scope of the book down. I usually take the list of chapters and re-order them a few different ways. Then I pare them down to the must-have chapters and the want-to-have chapters.

The must-haves are what I call the minimally shippable book. This is one of the things I really like about Agile development is that it does teach scoping pretty well. The other chapters that I want to write will be added as time permits. These are the chapters I usually reserve as stretch goals in my Kickstarter, although I also have other chapters beyond those stretch goals that I keep in my back pocket.

The nice thing about extra chapters is that you may find your main list ends up not having enough content. Then you can add some of the want-to-have chapters to make up the difference.

Anyway, all of this is to say is that you need to write 4-10 chapters to really find out what your writing pace is. Once you know that, you can average it out and predict how long it will take you to write out the minimally shippable book. This has worked pretty well for me. I know what my speed is and then I usually tack on 1-3 months on top of that because of vacations, trips and the inevitable sickness that seems to pop in when you least expect it.

Code Examples

Github has become the defacto location for storing code. To keep things simple for my readers, I have started putting all of my book’s source code there into specific book related repositories. I can then add a link in the book’s text and from my various vendor websites.

You can theoretically hook up a continuous integration service to Github or the like that can run linters and tests against your code. While I haven’t done that, I think that is probably a really good idea and I may try that for a future book.

Foreign Audiences

Getting your book to foreign audiences is a bit trickier. Fortunately, Amazon, Gumroad and Leanpub do sell internationally so technically people anywhere in the world can have access to your books. However if you want them to be able to read it in their own language, that becomes much more difficult.

I have had a couple of people reach out to me about translating my books. You have to be careful with this sort of thing because you don’t know if they are reputable or not. If you want to work with someone and share the profits, Leanpub provides a way to do that. However they don’t protect you if you give your book source away and they end up posting the translation somewhere else.

There are services like Babelcube that you can use to get your book translated. I have yet to try one of these, so I can’t really comment

Ebooks versus Print

You will make the majority of your money off of eBooks. So it is definitely worth the effort to create all three of the most popular formats: PDF, epub and mobi. According to Leanpub, PDF is, by far, the most popular.

For print books, I have used Lulu and more recently, Amazon’s Createspace. Amazon’s setup wizard is better than Lulu’s. However they each check your content differently. They will each tell you if your screenshots are too low resolution. Amazon will run a spell-check on your work.

You need a 300 dpi image for your cover art, both front and back. Otherwise it will look fuzzy. You are supposed to have 300 dpi screenshots, but I have found getting screenshots at that resolution to be next to impossible. Get them as high as you can though.

Note that for the eBook cover, you do NOT want a 300 dpi image as that will make the book’s download size much larger than it needs to be. What that means is you get to keep two versions of the book.

Also note that both Amazon and Lulu do NOT want the cover as a part of the print version of the PDF. The cover needs to be separate.

Book Revisions

As a technical writer, I like to keep revisions of my books. So I use Git for that. All my source files go into a Git repository and saved in Dropbox and Bitbucket. I am thinking about switching to Gitlab if I start using technical reviewers because they have nicer policies for private repositories.

Wrapping Up

I hope you have found this somewhat disjointed article helpful. I am going to write some more about the pros and cons of indy publishing in a separate article. Feel free to ask questions in the comments if you have any questions.