"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."
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.
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 'fab -h <target>'. And the way I create my Fabric scripts is basically what Zed describes above.
It's amazing how brutal most programming tools are to install. I feel like I am alone amongst all the people I know in being the only one who doesn't have a clue about *nix's underpinnings, about what /etc/local is for, and so on.
I feel like a charlatan some days. On the other hand... I certainly can tell you if your "how to install" instructions are actually any good for reaching new programmers.
I feel the same. If you're lucky programs come with a readme.txt that explains the steps required to install it. Why the heck didn't they code that in shell script instead of english? It practically doubles the value of the software.
I used to not know that stuff. Then I installed Gentoo Linux, and was forced to learn it the hard way. I don't use Gentoo anymore, but installing it was like a crash course in how to get uncooperative Linux software to bend to my will.
This was years ago, so maybe Gentoo has become more user-friendly since then.
I used Lightspeed C many years ago to write a plugin for Aldus PageMaker. I later used C++ to make Jprobe Threadalyzer, but the experience was very different.
So honestly, I do not think I know C in any non- trivial sense.
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.
Exactly. I like what the mathematician Paul Halmos had to say on the same subject:
Archimedes taught us that a small quantity added to itself often enough becomes a large quantity (or, in proverbial terms, every little bit helps). When it comes to accomplishing the bulk of the world’s work, and, in particular, when it comes to writing a book, I believe that the converse of Archimedes’ teaching is also true: the only way to write a large book is to keep writing a small bit of it, steadily every day, with no exception, with no holiday. A good technique, to help the steadiness of your rate of production, is to stop each day by priming the pump for the next day. What will you begin with tomorrow? What is the content of the next section to be; what is its title?
This is true of practically any endeavor. Mr. Shaw's example applies to learning as well as teaching. Since he plays guitar, he probably appreciates the larger implications of what he's done with LPTHW.
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.
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.
The trick though is that you need detail 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.
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.
FWIW, "Learn Python the Hard Way" has the words "beginner" all over the place and is quite obviously not intended to be a reference. This kind of book is designed to offer training and practice for a complete beginner, not to be a knowledge repository for use by an intermediate+ programmer.
An object, function, etc, can only be in exactly one namespace. e.g. "File" or "Net", but not both. What if a class can be used to accomplish multiple goals? The example code will end up in some obscure corner of your deeply-linked language reference pages.
No... a single .html file that contains all examples in all categories (or namespaces in your case) is much more useful than any alphabetical reference.
Note that the single examples.html page does not try to provide a reference. It provides example code, and that's it. No noise.
Ah, looks like we were talking past eachother. You were saying that you preferred "cookbook" style books, and gave examples of how to organize one of them. I was saying I liked "language reference" style books, and gave examples of how that should be organized.
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.
Really? Mini-hell? He posted a request for the author to take it down, the author agreed in the very first reply to this request, and as far as I can see, it was acted upon in less than 12 hours.
The flap that followed was a disagreement about the style of Zed's request. A semantic argument, which is pretty far from an ongoing personal torment.
Part of what followed was a disagreement about the style of Zed's request, another part was the plagiarizer trying to explain that he wasn't really plagiarizing when quite clearly he was.
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.
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'm all for people writing their own inspired rendition of the book, since it's a method that works. I'm helping a couple folks right now actually.
But the last thing I want is some half-assed copy of my book out there where some dude just rips out Python and puts in his favorite fanboi language like it'll fit. That will only confuse and deter people trying to learn, and it'll come back on me and my book not on them.
That's why my license says you cannot modify my book.
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.
Or, they've had System Administrators doing it for them their whole career and have no real clue what's involved anyway.
I find this hard to believe. Maybe if one is still living in the mainframe era and doesn't have a truly personal computer at all. Do you have any real examples of this?
My current employer has about 50 programmers and another 50 semi-programmer scientists all working on Linux. None of them have root access to any machine except their OSX laptop and most don't know how to install software thats more difficult than drag and drop.
There's certainly multiple levels of comfort with software installation in this environment. Many of our good programmers get frustrated and end up asking systems to install programs or work almost entirely on their OSX laptop. Personally I don't find it too limiting because I am comfortable installing in my home directory.
I used to work as a sysadmin at a small development shop that had 6 programmers. Those guys didn't have root access either, but it's not because they weren't competent; it was the only way we could keep the machines consistent. Otherwise, people were installing things all over the place and, in a lot of cases, the same program would be installed differently on each machine.
The reason system administrators have responsibility for installing and configuring software on production systems isn't because programmers don't know (or can't learn) how to do it themselves. It's typically because production systems are multi-user with uptime SLAs, meaning that software must be installed and configured in a reliable, repeatable way that works for everyone, not just one person.
The fact that sysadmins do often have that responsibility, though, means that sometimes programmers have less incentive to learn it themselves.
There are programmers like this today. They can install Windows and MS Office but once something more complex happened in their Workstation at the office, they'll call Sys Admin to fix it for them.
It's a mix of laziness and doesn't want to know more outside VB/C#. It's for an excuse to get a coffee break, a smoke break, or something else.
The programming team I currently work with is like this. The shop is PHP (legacy) and Django (new); but no one has any tools on their own computers. All development is done on a series of servers: alpha to beta to pre-production to production.
Not a specific example that I'm willing to describe in public, no. It's more common among junior and student programmers, for languages like C++ where there are lots of compiler and linker settings that are frequently different from one installation to the next, and where heavyweight IDEs are involved (Visual Studio, Eclipse).
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!
Maybe this is the wrong way to go about it, but could I do it without a framework? I've read a little bit about MVC design, and I was thinking, I'd hack everything together and try to make it work my self. And then go back and try to make it fit the MVC design.
How strong of a grasp would I need on object oriented programming to make a go at learning GAE without (or maybe even with) a framework? Thanks for the help so far!
I think it'd be a lot harder w/o a framework since you'd have to deal with a lot more low level stuff. Webapp is pretty much the most minimalistic cgi framework you'll find...
Though there is a lot of interesting stuff you could do with a lower level of access to the datastore.
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.
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 'fab -h <target>'. And the way I create my Fabric scripts is basically what Zed describes above.