
How To Write a Learn X the Hard Way - fukumoto
http://sheddingbikes.com/posts/1288945508.html
======
sghael
_"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.

~~~
raganwald
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.

~~~
jeebusroxors
Just because you used it as an example here are a few quick resources to help
understand filesystem layouts a bit better.

A real quick overview:

* <http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard>

More in depth:

* <http://www.pathname.com/fhs/>

~~~
rhizome
I prefer "man hier" at the command line. Much more succinct than either of
those:

e.g. <http://linux.die.net/man/7/hier>

~~~
frou_dh
Cool! "TIL", as they say on reddit.

~~~
tav
For non-redditers, TIL stands for "Today I Learned".

<http://www.reddit.com/r/todayilearned/>

------
cschmidt
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.

------
stuartk
This looks like a really nice way to write a book, or in fact any other large
body of work.

It avoids the monolithic todo list item - 'write book', and breaks things up
into manageable chunks.

~~~
jsomers
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?_

~~~
FraaJad
Something on these lines is being done under the #PragProWriMo tag. Also see
[1]

[1] [http://praglife.typepad.com/pragmatic_life/2009/10/prag-
pro-...](http://praglife.typepad.com/pragmatic_life/2009/10/prag-pro-wri-
mo.html)

------
jasonkester
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.

~~~
palish
_alphabetical_?

I'd rather have a listing of examples by category.

Such as:

    
    
      Category: Net
      Example:  here is how to download a webpage,
                parse its URLs, then download those
                URLs recursively.
    
      <example source code here>
    

An alphabetical list of classes is like an alphabetical listing of tools in a
toolbox. It's like, great, but _how do I use them_?

~~~
jasonkester
Alphabetical, respecting namespace:

    
    
      System.File.Open
      System.File.Write
      System.Net.WebRequest
    

So naturally, you get like things grouped together. Assuming your language has
a sane library, your concern shouldn't be an issue.

Of course, if your "library" consists of 4000 functions named things like
"mysql_get_connect" and "DateFormatUTC", then yes, you're screwed.

~~~
palish
Namespacing is nice but not sufficient.

What you want are _examples_ sorted by usage.

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.

~~~
jasonkester
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.

Sorry for the misunderstanding.

~~~
palish
Sorry!

------
kreek
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.

~~~
akira2501
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.

~~~
kreek
I did say it was 'mini' :)

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.

Then the offending party made a lot of noise about it.
<http://news.ycombinator.com/item?id=1874889>

Being slandered in public is not ongoing personal torment, nor is it a day at
the beach.

~~~
akira2501
I'm not defending Martin, by any stretch. I'll agree with your assessment
there.

On the other hand, I don't think Zed should be particularly surprised by his
reaction. Nor do I think he's ignorant to its cause.

------
runjake
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.

~~~
ciupicri
Zed's complaint about the Ruby fork: [http://github.com/martinemde/learn-ruby-
the-hard-way/issues/...](http://github.com/martinemde/learn-ruby-the-hard-
way/issues/1)

~~~
krainboltgreene
Just a note, he may be talking about Learn You An Ruby For Awesome Power:
[https://github.com/krainboltgreene/learn-you-an-ruby-for-
awe...](https://github.com/krainboltgreene/learn-you-an-ruby-for-awesome-
power)

While LYAR(FAP) is similar in style, it's not a copy. LYAR(FAP) was actually
started about 3 months before LPTHW, though restarted multiple times.

------
Goladus
_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.

~~~
nene
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?

~~~
zerohp
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.

~~~
trafficlight
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.

------
noahc
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!

~~~
grandalf
There is a very nice, simple step-by-step tutorial for app engine:

<http://code.google.com/appengine/docs/python/gettingstarted/>

~~~
noahc
I've already looked at that, but I was looking for something without the
webapp framework. Unless I'm mistaken it uses the webapp framework.

~~~
grandalf
What framework do you want to use?

~~~
noahc
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!

~~~
grandalf
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.

------
athom
Should have called it _How To Write a "Learn X the Hard Way" the Hard Way_

EDIT: Change "How" to "Learn"

