Electronic Books are Software

Electronic books are not software strictly speaking, but we can certainly treat them like software in many way. The similarities between books and software:

  • Software programs have text.
  • We need to check the quality of software.
  • At certain point we upload the software to a production server or to be sold.

Integrated Writing Environment (IWE)

Tooling is the biggest difference between software development and book authoring. Software developers have it easy! Let’s start with the integrated development environment (IDE). There is nothing like it for writers as far as I know. You have your outline. You have your chapters. These are usually separate Word or PDF documents containing comments from editors and reviewers. You can’t get a quick overview of your book project, the way you can in an Eclipse workspace.

If I open a Word document either in Word or OpenOffice I am always a bit afraid that the application will crash. Especially if it is a big document with a lot of comments. It might have to do with the fact that I am working on a Mac for several good reasons that I don’t want to go into right now. See, I think that the Microsoft Word team has something against Macs. Last time I checked the OpenOffice application required a Java Runtime Environment (JRE). Java seems to be not that well supported on Mac OS X. Also I have the feeling that OpenOffice doesn’t handle Word documents completely as one would wish.

If it was up to me I would have gone with plain text documents. Some type of XML to allow for special styles and formatting. Another feature I would love to have is smart autocomplete. The editors mentioned above tend to do unpredictable things when autocompleting. It bugs me so much that I have autocomplete turned off most of the time.

The keyboard shortcuts are too hard to remember. Ideally there should be only half a dozen keyboard shortcuts, that do multiple things depending on the context. For instance a “quick fix” keyboard shortcut like the one in Eclipse. Another must-have would be to have the Vim key bindings.

The Integrated Writing Environment should be able to adapt to my wishes. For instance if I want to apply a style to the word “NumPy” such as bold and extra large fonts, the IWE should ask me once whether I would like this style to be applied to “NumPy” from now on. And I must be able to change this behavior with custom rules, without having to learn a new scripting language. Eclipse has so called “Code Templates” so I would like to have a similar capability in the IWE without having to use Visual Basic or similar. OK, I admit that I am more comfortable with Eclipse and Vim then with Word and OpenOffice. I did try my best to learn and I do know a bit of Visual Basic, in case you are wondering.

Concurrent Version Control

Working on the same document with multiple editors and reviewers is pretty painful. Google Docs has improved a lot on this, but is still not ideal. I don’t think that I can work in Google Docs for extended periods of time. What is needed is a version control system (like Git, Mercurial, Subversion or CVS) or a content management system for book projects. It should be open-source, because we can’t trust a single company like Google. The system should be secure, easy to host and install.

Errata Tracker

And we need an issue or errata tracker. We want to pinpoint exactly to which word, sentence or larger chunk of text a ticket is referring. The IWE should have some smart way to annotate the document with the corresponding issues.

Continuous Books

Always be shipping or launching or whatever! Once the e-book has been bought by real customers it would be great to be able to frequently release patches with minor edits (and charge them of course). What we require is a continuous integration server that does some automated checks. For instance, spelling checks and a diff with the previous version after committing changes. If there are differences occurring that have nothing to do with reported issues, the build should fail. Additionally, we must check whether we are using the appropriate conventions and format. Again this should be trivial if we were using XML. The build would create several artifacts such as ePub, Mobi and PDF files. After a quick sanity check with the click of a button, we should be able to upload the e-book to be sold. The readers would then get notified by e-mail, Twitter or the Notifications app in Google Glass that a new book edition is available.

Disclaimer: this post was written based on my own book writing experience. I know technical writers who had similar issues. These ideas and opinion are my own and are partially inspired by others.

Items of interest for March 25, 2013


By the author of NumPy Beginner's Guide, NumPy Cookbook and Instant Pygame. If you enjoyed this post, please consider leaving a comment or subscribing to the RSS feed to have future articles delivered to your feed reader.
This entry was posted in Uncategorized. Bookmark the permalink.