News for hackers. Stuff that matters.
Re:How To Write a Learn X the Hard Way by jasonkester on Saturday November 06, 2010 @05:15AM (#1876520)
Alphabetical, respecting namespace:

  System.File.Open
  System.File.Write
  System.Net.WebRequest
So naturally, you get like things grouped together. Assuming your language has a sane library, your concern shouldn't be an issue.

Of course, if your "library" consists of 4000 functions named things like "mysql_get_connect" and "DateFormatUTC", then yes, you're screwed.

Re:How To Write a Learn X the Hard Way by palish on Saturday November 06, 2010 @06:02AM (#1876565)
Namespacing is nice but not sufficient.

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.

Re:How To Write a Learn X the Hard Way by jasonkester on Saturday November 06, 2010 @06:16AM (#1876588)
Ah, looks like we were talking past eachother. You were saying that you preferred "cookbook" style books, and gave examples of how to organize one of them. I was saying I liked "language reference" style books, and gave examples of how that should be organized.

Sorry for the misunderstanding.

Re:How To Write a Learn X the Hard Way by palish on Saturday November 06, 2010 @07:19AM (#1876663)
Sorry!