From: Kevin Date: 2011-08-03T09:27:33+09:00 Subject: Re: Documentation Improvement Proposal I would like to touch on a more general issue I've had with language docs of all kinds not limited to programming languages either. The big issue I tend to have is that the documentation is essentially a dictionary for various functions, the "how" portion or the grammar is usually located in a separate book or document which makes it more difficult to put things together. It would be wonderful if any refresh to Ruby's documentation made a concerted effort to make sure that it is simple to cross-reference the grammar with method definitions and other example elements. Right now documentation across the board (Not just Ruby's.) in my experience seems to be a list of definitions and not much else. Imagine trying to learn a second language by just reading a dictionary and not being told about how to structure nouns, verbs, etc. Or more accurately imagine learning them separately. It isn't enough to have good code samples, the samples have to be integrated with the rest of the language as a whole, integration has to be pervasive. If a function G in example 2010232 takes a block as an argument a user on the doc site should be able to select that argument and find out more about what a block is in Ruby. Preferably in a way that doesn't take the user away from the code they started out looking at.