How To Write a Learn X the Hard Way
sheddingbikes.com
sheddingbikes.com
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.
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.
A real quick overview:
* http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
More in depth:
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:
This was years ago, so maybe Gentoo has become more user-friendly since then.
Do you know C or would be interested in learning it?
So honestly, I do not think I know C in any non- trivial sense.
It avoids the monolithic todo list item - 'write book', and breaks things up into manageable chunks.
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?
[1] http://praglife.typepad.com/pragmatic_life/2009/10/prag-pro-...
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.
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>
System.File.Open
System.File.Write
System.Net.WebRequest
Of course, if your "library" consists of 4000 functions named things like "mysql_get_connect" and "DateFormatUTC", then yes, you're screwed.
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.
Sorry for the misunderstanding.
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.
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.
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.
I've already run across LPTHW forks for Clojure and Ruby on Github -- two languages that don't transpplant well into LPTHW, but hey.
But the last thing I want is some half-assed copy of my book out there where some dude just rips out Python and puts in his favorite fanboi language like it'll fit. That will only confuse and deter people trying to learn, and it'll come back on me and my book not on them.
That's why my license says you cannot modify my book.
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.
Or, they've had System Administrators doing it for them their whole career and have no real clue what's involved anyway.
It's a mix of laziness and doesn't want to know more outside VB/C#. It's for an excuse to get a coffee break, a smoke break, or something else.
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.
The fact that sysadmins do often have that responsibility, though, means that sometimes programmers have less incentive to learn it themselves.
http://code.google.com/appengine/docs/python/gettingstarted/
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!
Though there is a lot of interesting stuff you could do with a lower level of access to the datastore.
EDIT: Change "How" to "Learn"