4 ms·
"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
by sghael 16y ago
"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 16y agoIt'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 16y agoJust 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 http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard More in depth: * http://www.pathname.com/fhs/ http://www.pathname.com/fhs/
- rhizome 16y agoI prefer "man hier" at the command line. Much more succinct than either of those: e.g. http://linux.die.net/man/7/hier http://linux.die.net/man/7/hier
- frou_dh 16y agoCool! "TIL", as they say on reddit.
- tav 16y agoFor non-redditers, TIL stands for "Today I Learned". http://www.reddit.com/r/todayilearned/ http://www.reddit.com/r/todayilearned/
- SkyMarshal 16y agoAgreed, 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://linuxcommand.org/lts0040.php http://rute.2038bug.com/node20.html.gz http://rute.2038bug.com/node20.html.gz
- jules 16y agoI 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.
- pjscott 16y agoI 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.
- alnayyir 16y agoYou're relentlessly modest. Do you know C or would be interested in learning it?
- raganwald 16y agoI 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.
- alnayyir 16y agoWould you be interested in being a test subject for a C book?