
Zed Shaw's Template for "Learn X The Hard Way" Books - nbashaw
https://gitorious.org/learn-x-the-hard-way/learn-x-the-hard-way/blobs/master/README
======
zalew
A few bits that caught my attention and perfectly show why Zed's publications
are so good:

 _> 1\. Use just a simple editor like gedit, notepad+, or Textwrangler. NO
vim! NO emacs!_

 _> 2\. Do not have them use git or other RCS tools. They're here to learn
code, not git._

 _> 3\. Make it work for Windows, OSX, and Linux if you can._

 _> 4\. The install of your language should not involve tons of steps._

 _> 1\. Your book should educate people, not indoctrinate them. If you find
yourself talking constantly about how awesome your language is and how it will
change their life, then you're not educating, you're just making another cult
follower. Leave the decision of whether the language is good to the reader._

 _> 4\. Lightly make fun of programmers and inoculate your student against
religious wars over syntax, idioms, editors, tools, and anything else that
gets in the way of them learning. Remember, you are writing this book for
them, not your fellow coder friends._

This should be the mantra for everyone who writes a tutorial (which often land
here on HN) or any other form of introduction into technologies. Way too often
authors waste a huge chunk of their educational material on shoving their
tools of choice down readers' throats. 'hey, you want to learn rails? ok, now
buy a mac, install git, learn emacs, download my dotfiles...'.

TLDR: want to educate? be agnostic.

~~~
wturner
All education is a form of indoctrination. When you teach a kid to read you
are indoctrinating them, but you do so with the assumption that if you don't
teach them to read they will be worse off. So you indoctrinate them. As we all
go through life people are interacting making similar judgement calls based on
time, place and circumstance. So indoctrination in that regard is omnipresent
and has a good side. Sorry to be off topic but I felt like typing that. I
agree that we should fight our shallow inclinations to sensationalize in ways
that diffuse "robust" learning.

~~~
zedshaw
No, and I'll give you my distinction that separates education from
indoctrination:

Education's goal is to teach you something so that you can then go on without
them, thus why they teach a wider range of topics within a subject.

Indoctrination's goal is to make you dependent on the educator, thus why they
focus on only their version of the subject and squash differing opinions using
propaganda tactics.

For example, you don't have to go back to your highschool math teacher to use
Algebra or back to your grade school to read something. You are independent
and may never set foot in your school ever again, but can still do these
things.

If you teach someone that Python is the one true language and use propaganda
to make them want to use it, then they'll be dependent on that language and
the community in order to write code. Even simpler is if you only teach them
git and github then you've indoctrinated them into always needing github to
share code.

Bad kinds of education are like History classes that teach fairy tales like
"George Washington never told a lie." These are indoctrination masquerading as
education because they make the student dependent on the country for their
identity.

The reason indoctrination like this is bad in programming though is because
programming languages and tools die all the time, and when they do it destroys
these people the indoctrinators have made dependent on the technologies. It
also smacks of a con that's covering for shit technology that can't survive on
its own merits.

Finally, finding a particular topic in the gray area between them does not
disprove that there's a difference. Rational people don't think in binary, so
this is a continuum where you could find some topics that require a bit of
indoctrination, and some where it's the complete wrong approach. In my
opinion, programming education only has indoctrination because that lets
shitty technology hide behind propaganda.

~~~
wturner
I agree that everyone should strive for the intent and ideals you're talking
about (IE not making people dependent etc) But I still hold to my view in
terms of the definitions.I think indoctrination is like social order, to a
certain degree it is inescapable and inherently part and parcel to learning
anything involving reading and writing. But I complete agree with the ideals
you believe we should all strive for and the methodology etc. I do think there
is a staunch distinction between the indoctrination of people learning through
the state or a church or whatever, and the more interpersonal empathetic
methodology of teaching with an intent to facilitate independence. The irony
is most staunch ideologues would probably agree, then go off and completely
contradict it with their actions :). Around and around we go...

------
danso
If you've never taught beginners how to program, then you should obsessively
follow Zed's advice...I just cringe whenever I see even a mention of "git" or
any other development tool in the context of beginners coding.

I can only say that it is nearly impossible to underestimate the technical
unfamiliarity of this audience. Opening the command line terminal is
bewildering to them. Not understanding why 'ls' worked a minute ago but not
now (it's because they're in the interactive interpreter) causes rage.

You may think you're enticing the beginner by teasing all the cool things
they'll eventually get into, but it ends up being a disservice. They're
already entering a world of confusion and frustration, no need to add
orthogonal concepts to the mix.

~~~
btian
I agree in principle. However, sometimes it is useful to bundle things
together if that's how things work in the real world, like Ruby on Rails +
Github + Heroku in a RoR book. Then again, it would be counter-productive to
add in totally irrelevant things like vim or emacs.

~~~
orangethirty
I disagree. Adding github + heroku to a Rails book is a mistake. Too much time
is spent setting up things you don't really need to learn how to code with
Rails. Its a big drag. Imagine if at school you were taught how to write
cursive while also being taught how to hold the pencil. Shit gets complicated
too fast.

~~~
mhartl
It depends on your goals and your audience. The _Ruby on Rails Tutorial_
teaches web development to those who already have some programming experience,
and in this context including Git and Heroku is, for many readers, a big win.
True, the #1 complaint about the tutorial is that it includes so much more
than just Rails, but that's also the #1 compliment.

~~~
orangethirty
I like your book. Have read about a 100 times. Its good. But its not perfectly
marketed. The title does not fit the book. You are not teaching Ruby on Rails
per se, but web development _and_ deployment with Ruby on Rails. There is a
difference between the two. Imagine a beginner, who has no experience with
actual web development, but wants to try out RoR to find out what the big fuss
is. He/she finds your book, and starts reading it. Only to find out that
he/she has to learn about _n_ different things before learning how to include
a field in a model. Its frustrating. I know because I went through it. Even
though I knew git/heroku deployment beforehand, skipping over those subjects
proved difficult.

Though you do make a good point in your first sentence. It does depend on the
goals and the audience. But I think your audience is a bit too widespread.
People who have some programming experience are too wide of a net. I think if
it were sold as a book for people who havea bit of web development experience
then your conversion rate would be higher (from free reader to paying
customer).

Now, I'm not knocking on your accomplishments. My approach is merely from the
business perspective of marketing you book and videos. Have you tested other
approaches? If so, may you shed some light? I used to market/sell books on the
web, and find it fascinating. If you wish to continue this conversation
through email mine is in my profile.

------
zedshaw
Crap, well I just updated this and didn't rewrite the README. Let me fix that
real quick.

~~~
nbashaw
Sorry for submitting to HN with it not quite ready! Just stumbled across it
today and thought it was really fascinating. I'm working on a "learn to code"
product myself. Just watched your talk at Oredev in Sweden yesterday. Thank
you so much for sharing what you're learning!

~~~
zedshaw
Meh, I was just being lazy and should have done it yesterday. No harm done.

------
seancron
Just a heads up: this isn't the latest template according to
<http://news.ycombinator.com/item?id=4953872>

If you're looking to do a LxTHW, you should contact Zed to get the latest base
structure.

Edit: Also, if you want to write a Learn X The Hard Way you should read this
post about how to do it (<http://sheddingbikes.com/posts/1288945508.html>)

~~~
zedshaw
No, this is now the latest template. That's what I'm using in all my books
now, and it's coming from a more advanced project for writing music books
<http://orkestrix.org/>

My goal was, if I could write about code and music at the same time, then
making a build system for books would be easy. The above is the end result of
that work. Enjoy.

~~~
kroger
Orkestrix is nice.

I understand you don't want to use LilyPond because it is too complex, but you
may want to know that LilyPond comes with a tool to convert from ABC to
LilyPond (abc2ly). One could use it to write the music examples in ABC and
have LilyPond typeset them. I'd consider using a setup like this to typeset
the "final" version since LilyPond's typography is so nice.

------
danso
For a book like the Python book, what features of LaTeX were used? I usually
associate it with its ability to do fancy typesetting. But the Python book
looks like it could be done in mostly Markdown.

~~~
btian
lots of formatting features, easy to version control, able to convert to print
book and pdf easily, fully text based thus more predictable, and so on. LaTeX
can be used for any document from CV to an entire book.

~~~
zedshaw
Most of this is true, but I found that it completely falls flat on its face
once you want to do _any_ reasonable HTML output. htlatex is an abomination
that should be destroyed in the fiery pits of hell after some long quest with
a ring and some hobbits.

~~~
RodgerTheGreat
Presumably because LaTeX is designed for typesetting for fixed page sizes
while HTML is designed for creating content that reflows to different window
sizes and devices?

~~~
e12e
Not really - it is more that the various wrappers from tex to html are written
in the spirit of the ancient web, rather than a transform to (another) simple,
structured markup language. Somewhat odd considering docbook sgml should be a
good match for modern html+CSS. I've considered writing something better, but
have come to the conclusion that treating tex as output is just more
reasonable (ie write in something like rst/markdown etc).

------
minikomi
I just recently started attempting to teach myself how to teach with my friend
and his girlfriend as Guinea pigs using Zed's books as a guide.

Another thing I would add - go slow, but let the student explore and achieve
on their own. Small accomplishments without frustration are much more
motivating and "sticky" in the mind.

------
hahbhc
I am expecting Learn Scala the hard way. Scala for the impatient (first free
eight chapters) was a very good book, Scala Coursera was interesting. Some of
Zed advices are very practical.

------
alexk7
I guess writing "Learn 'alexk7's favorite C++ subset' the hard way" would
violate the "no indoctrination" rule... :)

------
kleiba
I know Zed is a vim afficionado - I wonder why he advises against it for
writing lxthw books?

~~~
zedshaw
No, I advise against _telling students to use it_ unless they're ready.

Use whatever the hell works for you if you're writing a book. Well, except
Microsoft Word.

~~~
kleiba
Ah, now I see. I misread that - thanks for the clarification!

------
gnu8
zed shaw's [something], let me fall all over myself to pay attention to this
rot.

~~~
roryokane
Your comment would be more helpful if you wrote what is actually wrong with
this book template, or with Zed Shaw’s works in general.

