Zed Shaw's Template for "Learn X The Hard Way" Books
gitorious.org
gitorious.org
> 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.
1. It's a structure problem, so you have to go back to organizing the concepts and how each chapter flows. Try changing the first lesson as a way to start rethinking this.
2. It's an audience problem, so you have to go figure out who the book is really for and then constantly try to write it for them. Try even changing who it's for and then see if that makes the book work for them.
Zed is specifically referring to this usage. You should never assume you are doing the Right Thing in programming, because you probably aren't, at best you're doing the "least wrong" thing for your situation.
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.
This is good advice for Zed's LxTHW brand, because those books are geared toward learning one particular language at a time. But in some contexts having an integrated approach can be an advantage. Readers of the Ruby on Rails Tutorial often tell me that they didn't really "get" web development until they saw how Git, GitHub, Heroku, and Rails all fit together. That's because the goal of the book isn't to teach Rails; it's to teach web development with Rails. Unfortunately, this means that some readers are overwhelmed by all the detail (and I may someday make a product to better meet their needs), but for many readers seeing the whole picture is a revelation.
frankly speaking, whenever I drop into a tutorial and it begins with an introduction to github or vim, I leave the page. it's because it shows the author isn't focused on solving my problem which is I am not familiar with some specific technology, he prefers to advertise his favorite tools for some reason and lock me in his way of doing things. just show me what I'm looking for, I will figure out the rest myself if I need it.
You're missing the forest for the trees. While it's true that those particular technologies aren't necessary, professional-grade development does require version control, shareable repositories, and deployment. Git, GitHub, and Heroku are just the solutions I happen to use in the book.
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.
If I'm teaching someone who doesn't know how a computer loops in a while loop or what a variable is, then you're advice is counter productive. None of that is useful for them and just gets in the way of what they need. At best you're just impressing them with a flashy demo that they may not even really understand.
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.
If you can't get someone started with the following steps:
1- Go to website
2- Download and press next until the prompt says "Installation Finished."
3- Click here to create a file and save the file on your desktop.
4- Press "Run."
5- See "Hello, World."
You already made it too damn difficult for week one.
All that other stuff is secondary. Getting the words "Hello, World!" (much less getting the screen to show 1 through 10 without dropping into an infinite loop) to show up w/o supervising the student is a huge victory. I can't tell you how long it took me to understand while and for loops, but it wasn't one or two days.
Getting someone set up and running with a semi-significant website is an unrealistic goal to accomplish within a few months... well, if you want that site to be reasonably coded, that is.
People with lots of experience forget that the basics, for a total beginner and near technophobe (as I was 18 months ago), is very difficult. The real "oh, crap" moment came for me when I was first exposed to Emacs. I complained that, in today's day and age, it was utterly fucked-up that some stupid class would suggest you don't use a mouse. I was told that that statement was probably the biggest indicator of my newbie status than all the horrid code I could demonstrate up to that point. Just remember that people aren't ready to learn a bunch of new tools and they aren't ready to give up familiar tools at the start.
Oh, you probably just need to tell them to download Pry.
http://gitorious.org/learn-x-the-hard-way/learn-x-the-hard-w...
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)
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.
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.
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.
Use whatever the hell works for you if you're writing a book. Well, except Microsoft Word.