How To Write a Learn X the Hard Way

<i>"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."</i><p>This applies to a lot more than writing a book and is great advice to anyone who is writing documentation for their code/project. I find this technique particularly helpful when writing a "How to get our development env up and running in 3 hours or less" document.<p>Most of the time I just write it down in a Google doc and share with my team. But lately I've been documenting all steps with Fabric, which has the dual benefit of being very readable ("self-documenting") code as well as a one-command setup script '<i>fab -h &#60;target&#62;</i>'. And the way I create my Fabric scripts is basically what Zed describes above.

I did the first two exercises last night with my 10 year old son. He really liked it. I realized that the LPTHW method is exactly the same way I learned to program as a kid. We went into the computer lab and they gave us worksheets with BASIC program listings on them. We typed them into the Apple II's and got them running, learning in the process. It was much less reading and more doing.

This looks like a really nice way to write a book, or in fact any other large body of work.<p>It avoids the monolithic todo list item - 'write book', and breaks things up into manageable chunks.

Nice instructions, but I personally hate programming books that are written this way. I suppose if you've made it to adulthood having never programmed a computer, you might need a book like this for your first language, but if you already know how to program, this format is just tedious and wasteful.<p>Give me a language reference that covers all the components of the language, followed by an alphabetical listing of the most common class libraries that you'll need to use. And that's it.<p>The trick though is that you need <i>detail</i> for everything. If I'm firing up a multi-dimensional array, your book had better have the code to do that, or it's worthless. Don't hold my hand on the learning side, but have all the information I need to use the language in one 2-inch thick chunk of paper on my desk.<p>Very few books get this right. I can think of exactly one, in fact: O'reilly's DHTML Definitive Guide. Copy that format exactly, and you'll produce a good programming book. Deviate into "teach yourself in 21 days" or "Cookbook" land, and you've lost me.

Posts like that are why I admire Zed. He just went through mini-hell getting an unauthorized copy of his work taken down. He could very well have said "F-U guys" and taken his ball and gone home. Instead he writes a lengthy post to help anyone write a book along the same vein as his.

I think that while the efforts are misguided, Zed should take people's efforts to transplant language X into LPTHW as a high compliment. He wrote a great, concise book and people were inspired.<p>I've already run across LPTHW forks for Clojure and Ruby on Github -- two languages that don't transpplant well into LPTHW, but hey.

<i>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.</i><p>Or, they've had System Administrators doing it for them their whole career and have no real clue what's involved anyway.

I would love to see learn Google App Engine the Hard Way. I'm trying to develop on it and it seems too big. I'd little bite sized chunks like this to digest at my own pace!

Should have called it <i>How To Write a "Learn X the Hard Way" the Hard Way</i><p>EDIT: Change "How" to "Learn"