Re: Documentation Improvement Proposal

On Tue, Aug 2, 2011 at 11:03 PM, Josh Cheek <[e-mail]> wrote:
> On Tue, Aug 2, 2011 at 7:27 PM, Kevin <[e-mail]> wrote:
>
>> Right now documentation
>> across the board (Not just Ruby's.) in my experience seems to be =C2=A0a
>> list of definitions and not much else. =C2=A0Imagine trying to learn a
>> second language by just reading a dictionary and not being told about
>> how to structure nouns, verbs, etc. =C2=A0Or 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 desperat=
ely
> 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 i=
s
> in the docs. Or, if it is, it needs to work with the current style of doc=
s,
> because much more frequently I just want to figure out "what was that met=
hod
> 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, a=
n
> 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=3Drecord_hash[:foo]
  self.property2=3Drecord_hash[:bar]
end

What I really had was something like:

fill(record_hash)
  a=3DClass.new
  a.property1=3Drecord_hash[:foo]
  a.property2=3Drecord_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=3DClass.new
class_instance2=3DClass.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=3Dclass_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 thing=
s I
> take issues with. The first is presentation, I prefer the ruby-doc.org st=
yle
> of presentation. The second is completeness, rdoc.info is much more compl=
ete
> 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, whic=
h
> 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-d=
oc
> much better than the list at the top of rdoc).
>
> Anyway, that's my two cents.
>