News for hackers. Stuff that matters.
Re:How To Write a Learn X the Hard Way by jasonkester on Saturday November 06, 2010 @04:36AM (#1876483)
Nice instructions, but I personally hate programming books that are written this way. I suppose if you've made it to adulthood having never programmed a computer, you might need a book like this for your first language, but if you already know how to program, this format is just tedious and wasteful.

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.

Re:How To Write a Learn X the Hard Way by Goladus on Saturday November 06, 2010 @09:55AM (#1876877)
FWIW, "Learn Python the Hard Way" has the words "beginner" all over the place and is quite obviously not intended to be a reference. This kind of book is designed to offer training and practice for a complete beginner, not to be a knowledge repository for use by an intermediate+ programmer.
Re:How To Write a Learn X the Hard Way by palish on Saturday November 06, 2010 @05:05AM (#1876509)
alphabetical?

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>
An alphabetical list of classes is like an alphabetical listing of tools in a toolbox. It's like, great, but how do I use them?
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!