I Just Started Writing a Python Book

And this is how I will be doing it

Erik-Jan van Baaren
Mar 9 · 6 min read
Photo by ASTERISK on Unsplash

In the past months, I wrote several articles about a programming language called Python.

I’ll be writing more of them in the coming year because Python is a hot subject. It’s being used in many industries and is the second most-used computer language in the world.

It took me a while to find a subject that:

  • I love writing about.
  • I know enough about.
  • Is a “hot” topic that people want to read about.

Python checks all the boxes!

I’ve also been wanting to write a book for a long time, so the idea to write one about Python popped into my head a couple of weeks ago.

After long consideration, I figured there’s not much to lose and a lot to gain. So I took the mental step and decision: I’m going to write a book!

Here are some reasons why this is a good idea:

  • I can write articles first and then reuse them for the book. The advantage? I can see how people react to them, adjust the content, and create a better book in the process.
  • If I end up with an unfinished book, at least I’ve written and shared a whole bunch of useful articles.
  • I can satisfy my desire to write a book and do something that truly excites me.
  • I’ll force myself to learn Python thoroughly.
  • I’ll force myself to become a better technical writer.
  • I can write about my journey and perhaps entertain and inspire other writers — starting with this article!

The Technology Stack

I’m a developer, a tech guy, a geek, a nerd, whatever you want to call it.

Also, this is a tech book, not just a regular book. So, the first question for me is: “Which technology stack can I use to produce a tech book?”

Requirements

I have a few requirements:

  • It better look damn good without too much effort from my side.
  • I don’t want to commit to one format right at the start. I want the flexibility to generate a PDF, EPUB, or even HTML. This way, I can change course if needed, e.g. create a website instead of a book.
  • I prefer some kind of plain text format because I find it much easier to work with.
  • The technology must support lots of code examples.
  • I want to use Git version control, I’m a well-mannered developer after all.

I don’t mind if things get a little technical. If I need to write a script to preprocess and compile my book, no problem. I have the skills so I better use them!

Twelve years ago, I wrote my master’s thesis in LaTeX. I love the sleek output it generates by default, but I remember I hated writing LaTeX.

What I do like is Markdown. It is plain and simple, and I know it well because I use it a lot. Here are the advantages of using Markdown:

  • It’s easy on the eyes.
  • It’s easy to write.
  • I already know it well.
  • It plays well with version control systems since it’s all plain text.
  • It’s easy to paste source code of all types into Markdown files. Markdown is used on sites like GitHub and Bitbucket for a reason.

Pandoc

With these requirements in mind, I started googling and found out about Pandoc. If you don’t know it: it’s a tool that converts from basically any format to any other format.

It’s the Swiss army knife of markup languages. Pandoc allows me to write in Markdown and convert to PDF, HTML, EPUB, and a whole bunch of other formats.

It uses LaTeX as an intermediate step, so I get the nice formatting of a LaTeX document while writing it in Markdown. Perfect!

I went ahead and installed the latest version of Pandoc (using Homebrew) and TeX Live and created an initial project that’s structured like this:

├── output
│ └── book.pdf
├── src
│ ├── build.sh
│ ├── chapter 0 - introduction.md
│ ├── chapter 1 - about python.md
│ ├── chapter 2 - installation.md
│ ├── chapter x - todo.md
│ ├── images
│ │ └── python-logo.jpg
│ └── metadata.txt
├── templates
│ ├── ....

For those who are interested, the build script looks like this:

pandoc -N \
--toc --toc-depth=2 \
-o ../output/book.pdf \
--template=../templates/eisvogel.latex \
--highlight-style=tango \
metadata.txt *.md
  • As you can see, I used a template I found somewhere on the web. This is certainly not going to be the final template. I’m still experimenting with that.
  • The options --toc and --toc-depth=2 create a table of contents at the start of the document.
  • The --highlist-style=tango option applies the default tango style to code listings. This is something I’ll likely need to tweak for better readability on monochrome devices.

So far, it seems this setup offers enough knobs and tools to make it work for a complete book though! It will require a lot more tweaking to get it exactly the way I like, but that’ll come later.

By now, I’ve found several articles from others with tips and tricks on how they wrote and formatted their book using Pandoc, which is encouraging.

The editor

I’m using Visual Studio Code to edit the project files. It’s free and it has loads of plugins. It supports Markdown and also has a preview feature for it. So while I type, it renders a preview of the chapter I’m working on, including images and source code listings.

It’s not as beautiful as the output of Pandoc, but it’s good enough to spot silly mistakes and get a general idea without having to compile to book each time.

My VS Code setup. Image by myself.

The Book Title

The next thing on my list is the book title. I wanted to have a title before I started writing the book.

This forced me to think about the approach I’ll be using to teach others Python programming. Will it be dry and formal? Or more colloquial?

I came up with a title in no time. I even registered the domain names for it. I’m going to keep it a secret, for now. It’s probably silly on my side, but I don’t want anyone to steal my title.

What I can tell you: the title implies it’s a practical book. There are enough formal, super exhaustive Python books out there that I will never be able to match.

What I can do is make it easy and practical to learn Python. If you read my book, you’ll get examples that you can use in the workplace. Stuff you can copy and paste into your own projects.

I want to teach the real-world, practical things that people struggle with every day. I can do this because I’m using Python in my daily work as well.


The Publishing Platform

I don’t know where I will offer this book. I do know that it will be an ebook. I see no future for paper books.

Pandoc gives me the flexibility to create multiple formats, so I might release the book in multiple ways.

Photo by rupixen.com on Unsplash

Since I have the skills to create a website and a web store, I could sell it myself as an ebook. I could even generate a custom book for each sale with Pandoc, including the name of the buyer to, perhaps, make it less prone to piracy.

I can also release it on Amazon Kindle. The obvious advantage is that it’s a big platform. There will be a lower barrier to buying on Amazon Kindle than buying it from the author’s site, I guess. It might also be easier for people to find.

Lucky for me, I’ve got lots of time left to research this subject. This book is going to take a while to write anyway.


A Collaborative Effort?

I’ll be writing about my journey to keep you entertained and informed. But I hope there’s something in it for me too. Writing about it helps me take a clear direction and make firm decisions. After all, the whole world is watching!

I’m a total newbie when it comes to writing books, so I’d love to hear your input. Feel free to share, e.g.:

  • Ideas for the book’s content. What would your ideal Python book look like?
  • Experience or tips about writing and publishing a book.
  • What technology to use for writing this book? Am I on the right path?
  • Where and how to publish it?

If you want to follow me more closely, you can sign up for free on my Substack page.

Better Programming

Advice for programmers.

Thanks to Zack Shapiro

Erik-Jan van Baaren

Written by

A writer at heart and software/data engineer by profession. Subscribe to my low-volume newsletter at https://techexp.substack.com/

Better Programming

Advice for programmers.

More From Medium

More from Better Programming

More from Better Programming

More from Better Programming

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade