By Zed A. Shaw

I've ran into a few people who think it'd be a good idea to take Learn Python The Hard Way, pull out the Python, and put in language X. This is like taking a Chinese cookbook and trying to make a Mexican version by swapping out all the spices for Mexican ones. It just doesn't work because there's more to food and a book like Learn Python The Hard Way than the ingredients.

Rather than have people try to copy my book and butcher it (which you're not allowed to do), I thought I'd explain how you can write a similar book for your favorite language. It's actually not hard if you remove some of my prose and play it straight. You could probably write one in a month if you spent a few hours a night doing it.

Here's how you do it.

Step 0

Pick your language and sit down with a fresh computer, absolutely nothing on it, and then install the following:

1. A shell/terminal.
2. A simple editor, NOT emacs or vi.
3. Your programming language.

The trick is you have to document everything you type step by step. The problem programmers have is they know how to install this stuff like it's second nature, so they skip details and important steps that non-programmers just don't know.

Once you have your instructions, erase the machine (or VM) and go through the steps again, manually. You'll run into stuff you missed and will need to fill those missing steps in.

Finally, once you've done one computer, say OSX, go repeat the whole process for Linux and for Windows.

These set of instructions will tell you whether a newbie can even use your language or not. If you have a huge number of steps involving complex downloads and compilation then you need to go fix a deeper problem. Get to work making your language easier to install and tighten up the instructions before you even begin.

Step 1

Now that you have your first language experience done you can lay the foundation for the book. It's really simple, you create the following:

• 52 more exercise files. I used Sphinx so I had 52 .rst files.
• 52 more language files to put the code for each exercise in.
• 52 more output files that you'll record the output of the 52 language files into.

After you get these organized (and feel free to look at how I setup mine with sphinx) you add a few more files:

1. An introduction that explains what they'll be doing and why.
2. Exercise 0.
3. A conclusion that tells them what to do when they're done.

This means your book is structured this way:

• introduction
• exercise 0
• exercises, code, and output for 1-52
• conclusion

With these files laid out you can then check them into a version control tool you like and you're ready to start writing. These files act like a TODO list that just crank on.

Why 52?

The reason I recommend 52 exercises is that it's a number that easily fits into various timing organizations. People can go one exercise per week and spend a year doing them, or six a week and take two months, or 13 week to finish it in a month. It also divides neatly so that you can do 26 that cover the very basics, then 26 for the next level of topics.

Step 2

You then go through and start giving each of the 52 exercises titles and short one sentence descriptions of what you'll teach. You might not be able to do all 52 but try to work out as much structure as you can.

One key though is use the first 26 exercises to get them typing simple code, but don't do logic yet. Use the remaining 26 exercises to cover logic and then more advanced subjects. Repetition and practice is important at the beginning so they get the syntax ingrained in their bones.

Your programmer brain will find this incredibly annoying and boring and repetitive, but this is what helps the learner. They need to do exercises and training, and that requires repetition that gets harder as they go. It's like lifting weights.

You now have this structure to fill in:

• introduction
• exercise 0
• exercises 1-25 covering basic syntax, I/O, variables, no logic.
• exercise 26, a "final exam".
• exercises 27-51 cover logic and then go through more advanced topics.
• exercise 52, "final exam".
• conclusion

A final note on the "logic" section is talking to people about logic and trying to explain it to them doesn't work. Yes, I know it worked for you, but you're weird like me, and actually I bet that's not really how you learned it. For everyone else memorizing truth tables and then learning how to read logic expressions with them is the way to go. I know, you'll think it's boring, but it works. They need repetition to get it baked in their brain the way you have it.

Step 3

Now you sit down to write each exercise, and you can do probably one or two a night and finish it fairly quickly. The catch though is you have to follow this mantra:

Less talk, more code. MORE CODEZ!

What makes the book work is that rather than blabber on and on talking about what you are going to teach them, you simply have them do it first, then explain it in the next exercise (or maybe a few later). This seems backwards, but what makes it possible is each exercise has a consistent repetitive format:

1. Short description of the small unit/subject.
2. The code they type in.
3. The output they should see.
4. Extra credit to help them explore the subject.

Every few exercises you give more explanation about what they just did so that they understand it intellectually, but now your explanations are easier because they've already experienced it. It's much easier to describe something someone's experienced after they've experienced it.

An important part of this is that you stress they are to focus on accuracy and attention to detail when getting their code to match yours. Attention to detail and spotting differences in text is the most important skill a programmer can develop, so stress it all the time.

Step 4

The final step is to publish it. Depending on how you do this you can publish it when you're "done" or put it up in a repository like I did and let people file bugs as you go. Letting people file bugs is great because they'll find errors you never would. The problem is then you sort of have to give your book away. It's your call, but I say put your book up and get the quality high.

For actual publishing I recommend using lulu.com so people can get a paper version of the book. It is actually easier for regular folks to learn to code out of a book. They're more used to reading books, and most normal people don't have dual monitors. It also costs you nothing and if you want you can set the price at entirely cost and the printed book will be very cheap.

Conclusion

The important thing about writing a book in the style of LPTHW is that you don't have to be a great writer to do it. By focusing on code and simple language to explain it you have less of a chance to screw up your descriptions.

Now, rather than try to copy my book verbatim, go write your own. It's not that hard.