How I wrote my book - the technical details
I recently released a book called Hiring Data Scientists and Machine Learning Engineers. I self-published the book via a platform called Leanpub. This post is about how I actually did my writing, primarily the technical details of my setup and workflow.
Let's say you've decided to self-publish a book...
When I decided to actually write a book, my main criteria was being able to create and distribute something high quality with the least amount of effort, while retaining a lot of control over the final product. As mentioned in my early blog post that talked about my motivation for writing the book, I came across Leanpub because a friend had published a book there.
Why Leanpub in particular?
In the era of social media, blogs, podcasts, and streaming video creators can essentially deliver directly to their audiences. Similarly, self-publishing is not only easier than ever, but also just makes sense for a lot of people. This is the age of fast turnaround and disintermediation, which is just a fancy term for removing the middle man (and usually replacing them with a "platform").
But why Leanpub? There are a lot of choices for self-publishing a book these days. I chose Leanpub for a few specific reasons:
- It's aimed primarily at technical content (computery stuff).
- It already has a lot of good data science and machine learning-related books and courses.
- It provides several nice authoring workflows (see below).
- It pays a good royalty rate (80% to the author).
- It allows you to publish and sell in-progress works.
- It allows you to set a minimum price and allows readers to pay what they want over that.
- It allows you to create coupons (including programmatically via API).
Overall I like how pro-author they are.
How I wrote my book
Leanpub has several authoring workflows available, including fully in-browser authoring, but I decided to use a their more developer-style workflow. It starts with writing the content locally in Markua, Leanpub's book oriented dialect of Markdown, using git for version control, pushing changes to a Github repo, and then finally Leanpub pulling the latest version of the source and building the ebook files in several formats for you.
I really liked writing that way, because it's similar to how I already write notes, documentation, and blog posts in my text editor (VS Code these days). Markua is close enough to vanilla Markdown that the Markdown extension I use with VS Code renders it well enough for writing. In the end you need to have Leanpub build updated ebook files to know for sure how things will look, but this is definitely not a deal breaker.
Pretending to be a designer
I enjoy making graphics, and even though I am a certified amateur, I decided to try my hand at creating the cover for my book. I created the cover and other graphics using Inkscape, which is a pretty incredible open source vector graphics editor.
The graphics I used inside the book, which were primarily decorative, were a mix of vector graphics I created by hand, modified public domain vector graphics, and equations typeset using LaTeX within Inkscape.
The build process Leanpub uses allows you to use SVG files directly, so instead of exporting my graphics to a bitmap format I used SVG, with the exception of the cover graphic.
Writing on a 6" screen
At some point while writing my book, it occurred to me that I could probably write directly on my phone. This is probably viewed as masochistic by many, but it seemed like a fun thing to try "because it was there".
To get this to work I installed an app called Termux, which is a terminal emulator and Linux environment for Android, available via F-Droid, an Android app store with only open source apps. Termux allows you to install and run a lot of the programs that Linux/Unix users expect to be able to run from the command line, including git.
Next up I installed git and ssh via the Termux package manager:
pkg install git
pkg install openssh
Once I installed git, I set up a new Github key on my phone following the usual process, pulled down my book repo and was ready to start writing. Since I was writing in a Markdown dialect, I looked for a Markdown editing app, ultimately settling on an app called Markor. The workflow is then identical to writing on a full-sized computer.
- Write some.
- Commit the changes in git.
- Push the changes to Github.
As you might imagine, long-form writing on a virtual phone keyboard is not the funnest way to write. The nice thing about a phone is that they tend to handle voice typing well. While I did that some, I prefer to type when writing. Fortunately the keyboard that I normally use is very small and designed with portability in mind: the Keyboardio Atreus. The Atreus is a small, split, columnar layout, mechanical keyboard. Yes, you need to be a keyboard geek to use the Atreus, but look, you've read this far for a reason.
So aside from small edits, I did most writing on my phone with the same keyboard I used the rest of the time on my computer.
What might be improved
Overall I've been happy with the choices I made and the process, but it was certainly not without room for improvement.
It would be nice to be able to build the book completely locally, if only for the sake of portability. What if I decide I want to take my Markua source elsewhere? Would I need to convert to a completely different format?
Another issue was sharing my work with others for editing and commentary. For people that are used to a Github centric workflow, I could share my source text with them and they could comment or make proposed changes just like they would with code. But for other people who helped me with the book, but who were not used to working with git, I would send them PDF or raw text, which was not ideal. It was not a showstopper, but it could certainly be improved.
What does it all mean?
Writing a book can be a long, often grueling process. It was nice to be able to use the tools I'm used to and to branch off into the (practical[?], but) whimsical as well.
If you have any questions about this process, please email/message me.
And don't forget to check out my hiring book at dshiring.com.