From 2008 to 2009, I wrote a book called “Invent Your Own Computer Games with Python” ( http://inventwithpython.com ) which guides young adults and complete beginners through learning how to program in the Python language. I’ve just completed the second edition of the book, which has been an exhausting amount of work. Looking back over it, I realized that it could have been a much less exhausting experience if I had made some simple preparations.

I’ve decided to write up this post on the lessons learned and the best practices for writing a technical book that aims to teach programming. This post will help me organize my thoughts so that I’m more prepared for my own future writing, but the practical tips can help others who aspire to write a book as well.

Other people have written on this topic before. Some of them reiterate the fact that you probably won’t make any money from your technical book, or at least, not compared the money you could have made by flipping burgers instead of writing. I’ll link to some of them here:

“How to write a book” (A Billion Monkeys Can’t Be Wrong blog) http://www.gigamonkeys.com/blog/2007/04/10/how-to-write-a-book.html

“Hard Work, No Pay: What’s the Point? (Charles Petzold) http://www.charlespetzold.com/blog/2007/10/081247.html

Do Not Buy This Book (Jeff Atwood’s Coding Horror blog) http://www.codinghorror.com/blog/archives/000971.html

What is it like to write a technical book? (Xaprb blog) http://www.xaprb.com/blog/2008/06/15/what-is-it-like-to-write-a-technical-book/

Writing a Technical Book: IronPython in Action with manning Publications (Michael Foord at the Voidspace blog) http://www.voidspace.org.uk/python/articles/technical-writing.shtml

General Principles I Realized

1 – This was a lot more effort than I initially thought it would be.

2 – The actual writing of the book took much less time than editing and revising it. And then there was publicity and trying to get people to read the book. (Making my programming book free to download was key to getting people to actually hear about it.) Writing a book is a months long project, but the writing is the easiest part.

3 – I learned things during the process that I couldn’t have anticipated before. I’ve written them down here for others to learn from my experience.

Things to Do Before You Start Writing or Outlining

There are many important decisions and questions that need to be completed before you write the first sentence of the book. Without completing these steps first, you will most likely set up yourself up for a lot of wasted writing and effort.

This is important to keep in mind, because writing the book is relatively easy and short. However, the editing of the book and getting it into a presentable state was by far the majority of the effort needed.

1 – Research what others have written on this topic.

Don’t reinvent the wheel. Find as many other books and papers on your topic as possible, and generate a list of them. Be exhaustive, and skim (if not read completely) all of these sources.

2 – Create a list of what you like about these books and don’t like.

Write down the things from these other books that you like and want to incorporate. And then write down the things you specifically do not like about these books. Are they too wordy? Do they cover too much or too little information? Do they not provide enough examples? Is the book too shallow, or does it focus on too few topics? Create an actual list and save it somewhere on your computer so that you can refer to it later. The act of typing up this list will solidify this in your mind.

A good place to check are the Amazon.com reviews of these books. What are other people saying about them? Do the people writing the reviews realize who the target audience of the book is? Are they making valid criticisms of the book? Are they writing generic, “this book is great” fluff reviews?

3 – Figure out the demand for this book and the target audience.

The world does not need Yet Another Programming Book that covers the exact same information in the exact same way as other books. What makes your book different? (In my case, I inverted the presentation of programming concepts by presenting the source code for games, and then explaining the code line-by-line. This was different than the “explain a laundry list of programming concepts” that many books take.)

This could come from covering topics that other books do not cover, or covering topics in more depth than other books do. Or perhaps you want to organize information into a book that is freely available rather than what only is available commercially.

Many projects start off when the author comes across an itch that they need scratched. If you’ve done your homework on all the sources available on the topic and are still wanting, it’s possible that others have this same need as well. However, remember that this project should cater to your reader’s needs more than your own.

Write down this information and save it on your computer somewhere.

4 – Figure out what you DON’T want the book to cover.

Make a list of things that you explicitly don’t want to cover. Check out your list of things you don’t like about other books. Avoid the urge to start writing on topics that you initially think are cool unless you give thought as to how it’s relevant to your project. “It’d be cool if…” is a thought that you should be skeptical of.

5 – Figure out your book’s copyright license.

U.S. copyright law states that your work is protected as soon as it is created in a tangible form. However, you can also file your work with the Copyright Office at http://copyright.gov. This may be useful for use in court later on. The filing fee is $35.

Additionally, I released my book under a Creative Commons license. CC is modeled after the open source movement’s OpenGL or BSD licenses, which allows others to copy and redistribute your work. I was more concerned with getting my book into people’s hands rather than making money off of it. The web makes distribution of electronic forms of the book incredibly cheap, and I thought it was improbable that I would see much revenue from the book anyway.

The Creative Commons license is flexible. I chose the Attribution-ShareAlike-NonCommercial license. This means that people are free to copy the work, but they must keep my name on it and if they make changes or extensions to the work, those changes must also be distributed under a Creative Commons license. The NonCommercial clause states that people cannot sell the work. (This was not in some early versions of the 1^st edition, which is how somebody is now legally selling that earlier edition on Amazon.com.)

6 – Have a Go / No-Go decision.

After doing all the preparation research, seriously consider if you should attempt to start this project. Do you have a clear idea of what the final product will be (and what it specifically won’t be)? Is this something that other people could use, and isn’t already available with some other book or website? Are you willing to spend your spare time over the next several months or even year writing this book? Will your topic be out of date by the time you finish the book? (The last one is especially relevant to technical books.) If after all the prep work you find that the book idea isn’t strong enough or something you’d like to work on for the next few months, don’t be afraid to walk away and try something else.

7 – Write the book’s featured programs.

This is mostly relevant to my book, where each chapter focused on the source code of a program. I didn’t have the programs completely tested before I began writing, so whenever I had to make a change to the program I would have to change the book. For example, every place where the book said “on line 17” would need to be converted to “on line 19” and then changed again to “on line 18”. Having the programs finished with high quality and set in stone would have reduced a lot of redundant, wasted effort.

The Book’s Format

This is largely a decision to be made by you. But I wrote “Invent with Python” using HTML and CSS. Other options include LaTeX or some specific word processor’s format. Use a format that you are familiar and comfortable with. I chose HTML because I didn’t want to spend the effort to learn LaTeX or Docbook before starting on the actual book’s content itself.

You could even just use a plain text format, and put off the layout and formatting until after the content is complete. This isn’t the path I chose, but it might have reduced the amount of effort I put into the book’s creation. This would be ideal if you want to decide on the format later.

One idea that I considered was writing a book in a wiki, which could offload much of the editing work to the public (that is, if anyone actually cares enough about the book). This is what I see at the wikibooks.org website. However, this format is more of a website (with hyperlinks to jump around the content) than a book (which has a more formal, linear format).

Be sure that whatever format you use, it is a format that can be converted to PDF easily. If you decide to produce physical hard copies of the book, most printers can work with PDF files. (I’ve had some difficulty with this using HTML, which I outline below.)

Organize Your Tools

I run Windows, and I found several pieces of software that helped me out:

1 – My text editor, EditPlus. http://www.editplus.com/

EditPlus is a fairly standard text editor with all the basic options. What I really found useful in it was that it had find-and-replace feature that supported regular expressions. Many people use Notepad++ too.

2 – Subversion aka svn (source control software)

Subversion is freely available software that can track changes made to your files. Not only does this act as a backup for your work, but you can always roll back changes you make and see an earlier version of your work. This is much more preferable than copying and pasting your folder into some ad hoc system of “book work backup1”, “book work backup 2”, “more book work backups”, etc.

I’d also highly recommend backing up your files to a flash drive, or some other place besides on your computer. Your time is worth far more than the $10 for a flash drive that saves you when your hard drive crashes.

If you use Dreamhost for web hosting (use promo code “COFFEEGHOST” for a $97 discount), they provide Subversion servers for your use as a part of even the basic packages.

If you check in zip or rar files (or any other file that is a collection of other files) be sure to also check in the files in them individually too. It can be very difficult to determine which version of the zip file contains a certain file (or a certain version of the file). Create a script that will automatically create zips from these individual files.

You absolutely need to have a backup strategy that involves copying ALL of your files to somewhere else because the computer you work on. Preferably somewhere online as well (think of if a fire destroys your home).

3 – HTML Validation http://validator.w3.org

Because I wrote the book in HTML, I wanted to make sure I was creating properly formatted HTML. There are many HTML validation websites and software that are freely available.

4 – pngout http://advsys.net/ken/utils.htm

All of my figures are in the PNG format (for reasons I go into later). pngout.exe can reduce the file size of PNGs without any loss of quality. It is an excellent tool. Don’t waste your time compressing your files until they are finalized.

5 –Memento http://download.cnet.com/Memento/3000-2072_4-10153930.html

Memento is some really simply, handy software that lets you create small post its on your desktop. This is a perfect tool for creating short lists and notes. Think of it as a mini-Notepad.

6 – PDFCreator http://sourceforge.net/projects/pdfcreator/

This creates a “virtual printer” that creates PDFs from any application that can print. I use this to “print” the HTML files of my book into PDF files.

7 – A spreadsheet to keep track of bugs. I didn’t need full blown bug tracking software for this project, but I did need to keep all the corrections and enhancements organized. I started out with bug tracking software, but it just became too much of a pain.

8 – Autohotkey was very useful for creating keyboard combinations that could automate common editing tasks. I wrote an autohotkey script that would copy the currently highlighted text, run a Python script, then paste the text over the selected text. The Python script would modify the contents of the clipboard to add HTML tags to either side of the copied text. This was a much quicker method than individually typing the tags on either side of the text. The Autohotkey script is located here and the Python script is located here (the Python script requires the Win32 extensions module for Python, available at http://python.net/crew/skippy/win32/Downloads.html ). These scripts aren’t very well documented, but can give you an idea of how they worked (email me if you want more specific instructions.)

Writing Tips

Use unique IDs instead of chapter titles, figure numbers, line numbers, and anything else that is referenced in multiple places and could change during the course of writing the book. Doing a search-and-replace of something like “Fig83UX9” or “LineNumRR9Y” is much easier than looking for more generic “Figure 1-2” or “Line 19”. Across many changes, it is easier for these things to get out of sync and become hard to notice typos. (Eh, actually your word processing software should have something that does this.)

HTML is great because you can add comments to it that are invisible when you view the file in a web browser. I make notes in HTML comments and mark them with TODO so that I can easily find them again. I also put comments down near anything that could change before the completion of the book. (A couple new versions of Python came out while I was writing the book, making it necessary to update the versions in the book.) (Don’t use HTML to write a book. Use a real word processor.)

Avoid use of “the figure above” and “the text below” types of descriptions. Replace them with actual figure numbers.

Most technical books have websites. You should have the general layout of your book’s website done before you begin writing (or at least in the early stages) so that you do not need to update URLs in your book if the layout changes. Dreamhost.com provides cheap (and mostly reliable) web hosting and domain names. Use the promo code “COFFEEGHOST” for a $97 discount.

The website should have VERY simple URLs. I have inventwithpython.com for the main site, inventwithpython.com/chapters/index.html for the table of contents of the online book (which means browsers only need to type in inventwithpython.com/chapters), inventwithpython.com/blog for the WordPress blog, etc. Do not have something like inventwithpython.com/sourcecode/examples/aug-4th/blah/woot.html. If you do, use a URL shortening service or just add redirection pages from shorter URLs.

Some people are funny. You might not be, even if you think you are. Humor can lighten up the book a little, but it is very easy to overdo it and make the book cheesy. When I wrote “Invent with Python”, I mentally gave myself a lobotomy first. This mindset makes the book a bit dry, but also dead simple and easy to read.

Keep a spreadsheet of all the bugs, TODOs, and things you’d like to correct with your book. Type up a description, along with the date you logged the bug and the date you fixed it. If it will take more than five minutes to change, then you should probably write it down. This may seem like a lot of busy work, but it is worth it to have a place that tracks issues.

Don’t delete things from this spreadsheet as you fix them, just mark them as “done”. I’ve sometimes changed something, then weeks later changed it back not remembering the reason that made me want to change it in the first place.

Also, be sure to fix bugs with your writing before writing new content. It’s more fun to write new chapters than to fix the old chapters, but making the corrections first will help prevent you from making the same mistakes again.

Make liberal use of the delete key. Read over each sentence, and if it doesn’t provide information that is necessary, get rid of it. Writing too much about a topic is a much more common problem than not enough.

Also, if you find a typo in your writing, be sure to look through the entire file for other instances of that same typo (or type of typo). I recall finding that I used the word “multiple” instead of “multiply” in one paragraph, and then found I made the same mistake in a later paragraph.

Dealing with Images

Don’t draw borders around your images. You can always write a Python script later to add them in, or add a border with CSS (if you are using HTML for the book).

If you work in Photoshop (or some other image editor), keep the .psd files with the same name as the resulting image. This way, if you ever need to make changes again, you can easily find the original photoshop file.

When making screenshots from your computer, crop out any distracting elements. For example, when I wanted screenshots of the browser, I try to first remove any toolbars or other tabs so that the reader can focus on the main content. I also change my Windows theme from Windows Classic (which I prefer) to Windows XP (which is more recognizable).

Use high resolution images (e.g. 300 dpi). You can always cut down their size later, but it looks ugly to enlarge a low resolution image. Keep the high resolution images somewhere with a filename that corresponds to the lower resolution images. Note that Word only lets you have at most 220 dpi. Make a lower resolution version of the image from the higher resolution version, and if you need to change it, change the higher resolution version and make a new 220 dpi version.

Your cover should have the title, your name, and perhaps a single, short sentence on what the purpose of the book is. Avoid using too many colors, needless pictures, and text. If you plan on making hard copies of your book, be sure the cover is at least 300 dpi.

Don’t use a screenshot of something that could be represented with text instead. Initially I used screenshots of IDLE’s interactive shell to show code that had been typed in. However, I ended up replacing it with text because the text would be more readable than the tiny text in a screenshot. Also, text can be highlighted and copy/pasted, while the text in an image cannot be.

Things I Learned About Teach Programming to Kids

First, kids can’t type. Presenting large amounts of code to kids to type in is itself a formidable challenge. I strived to keep the size of the game programs small, and also pointed them to the website where the code could be downloaded.

Also, whenever kids made typos, they would get completely alien error messages and have no idea where they went wrong. One example a reader emailed me was code they had typed where a comma had been replaced by a period. He wasn’t familiar enough with the error message to figure out where the problem was. I’ve added an online diff tool to the website where readers can copy/paste their code to and compare it to the code that’s in the book. The diff tool is called jsdifflib and is available at http://snowtide.com/jsdifflib

Summary

Hopefully these tips will provide some practical insights and preparations for writing your own book. Feel free to email me with any questions about what the book writing process was like.