Lessons Learned from Writing a Technical Book to Teach Programming

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 1st 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.)

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 quality and set in stone would have reduced a lot of 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.

2 – Subversion aka svn (source control software)

Page 2 of 4 | Previous page | Next page