News for hackers. Stuff that matters.
Re:How To Write a Learn X the Hard Way by sghael on Friday November 05, 2010 @09:41AM (#1873090)
"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.

Re:How To Write a Learn X the Hard Way by raganwald on Friday November 05, 2010 @10:16AM (#1873235)
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.

Re:How To Write a Learn X the Hard Way by jeebusroxors on Friday November 05, 2010 @10:20AM (#1873248)
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/

Re:How To Write a Learn X the Hard Way by rhizome on Friday November 05, 2010 @01:45PM (#1874116)
I prefer "man hier" at the command line. Much more succinct than either of those:

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

Re:How To Write a Learn X the Hard Way by SkyMarshal on Friday November 05, 2010 @07:47PM (#1875404)
Agreed, and man hier is always there if you forget something, don't have to go track it down on the web.

However, I found these useful too when I was learning it. Sometimes it just helps to read different explanations of the same thing till it sticks:

http://linuxcommand.org/lts0040.php

http://rute.2038bug.com/node20.html.gz

Re:How To Write a Learn X the Hard Way by frou_dh on Friday November 05, 2010 @03:33PM (#1874527)
Cool! "TIL", as they say on reddit.
Re:How To Write a Learn X the Hard Way by tav on Friday November 05, 2010 @09:16PM (#1875578)
For non-redditers, TIL stands for "Today I Learned".

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

Re:How To Write a Learn X the Hard Way by jules on Friday November 05, 2010 @12:15PM (#1873705)
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.
Re:How To Write a Learn X the Hard Way by pjscott on Friday November 05, 2010 @04:01PM (#1874647)
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.

Re:How To Write a Learn X the Hard Way by alnayyir on Friday November 05, 2010 @04:24PM (#1874738)
You're relentlessly modest.

Do you know C or would be interested in learning it?

Re:How To Write a Learn X the Hard Way by raganwald on Saturday November 06, 2010 @01:50PM (#1877360)
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.

Re:How To Write a Learn X the Hard Way by alnayyir on Saturday November 06, 2010 @02:47PM (#1877463)
Would you be interested in being a test subject for a C book?