From: Kevin Date: 2011-08-05T23:52:12+09:00 Subject: Re: Documentation Improvement Proposal On Tue, Aug 2, 2011 at 11:03 PM, Josh Cheek wrote: > On Tue, Aug 2, 2011 at 7:27 PM, Kevin wrote: > >> 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. >> >> > Maybe I'm missing something, but in my mind, that's what documentation is. > Switch it around, imagine trying to learn a second language, and desperately > needing to ask where the bathroom is, but every time you try to find the > translation for "bathroom" you wind up having to wade through three pages of > context / examples. No you don't Hypertext already solves that problem since the grammar related information is essentially metadata in this case. Besides your example only works in concrete cases. As it stands now dictionaries are effectively useless without understanding at least a small fraction of the language grammar if you are trying to find out how to do something abstract. This is where your example falls apart. A list of words is not going to help someone just learning how to form meaningful statements to form meaningful statements. > I think there is merit to what you are suggesting, but I don't think it is > in the docs. Or, if it is, it needs to work with the current style of docs, > because much more frequently I just want to figure out "what was that method > that returns an element from a hash, without invoking #[]" go to the docs > "oh yeah, #fetch". That process should be as streamlined as possible. If you > want to add other stuff as well, that's fine, but make sure not to impede > what I think is the docs' primary function, figuring out what method you > want, what it expects (signature), and what it does (a sentence or two, an > example or two). I maintain an internal application that deals with student records. Since I'm stuck on .net 2.0 and cannot use Linq I constructed a psuedo ORM and my model classes have a fill method to set the properties of a given instance. I had prepared the fill method a very long time ago and had not actually used it. (This code was part of a secondary code base when I created it and I was not the project lead at the time so my code did not see immediate use.) Because of this lag between creation and usage I did not notice the reason why Class.fill would refuse to actually set the properties of the class instance. I thought I had the logical equivalent of fill(record_hash) self.property1=record_hash[:foo] self.property2=record_hash[:bar] end What I really had was something like: fill(record_hash) a=Class.new a.property1=record_hash[:foo] a.property2=record_hash[:bar] return a end See the problem here? Assuming that the syntax is correct the two functions have semantically different meanings. Given the the second form of the function if fill is called on an instance of a class only one of the following statements will actually work: class_instance1=Class.new class_instance2=Class.new class_instance1.fill(record_hash) #Fails miserably since it returns a new class instance with set properties rather than setting the properties of the caller. A perfectly valid statement though. class_instance2=class_instance1.fill(record_hash) #This works since the second form returns a filled instance and thus requires a second variable to receive the return value in the calling code. Only the first form allows for class_instance1.fill(record_hash) to set the values of the current instance. A simple logic error that you may or may not pick up just by reading the function definitions. I think most would agree that it is ass backwards to have these kinds of details stashed away in treatises like the Pickaxe. The way people try to solve this problem, by including this kind of information on the main documentation website in the form of tutorials isn't enough. The tutorials are still disconnected from the API docs and vice versa. My point is that every language is the union of the given grammar and the definitions of vocabulary in the context of this discussion this means the method definitions we are used to. While it is often very useful for us to think of definitions and grammar as separate things this kind of thinking becomes a hindrance when trying to learn how a language works before one has properly internalized the grammar of the language. What that means when constructing documentation is that not making it easy to link API to language spec fosters a haphazard kind of learning that makes it more difficult than it needs to be to learn how to deal with abstract problems in the language of choice. > I'm generally satisfied with Ruby's docs. There really are only two things I > take issues with. The first is presentation, I prefer the ruby-doc.org style > of presentation. The second is completeness, rdoc.info is much more complete > to the point that I'm probably going to switch. It also has docs for gems, > which I think is really cool. And it filters the list as you search, which > okay. I just find its format harder to follow (possibly because I'm used to > ruby-doc, but IDK, I like that giant pool of methods at the top of ruby-doc > much better than the list at the top of rdoc). > > Anyway, that's my two cents. >