Documentation Improvement Proposal

Ruby
21

On Tue, Aug 2, 2011 at 7:27 PM, Kevin [email protected] 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.

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’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.

22

On Wed, Aug 03, 2011 at 12:03:27PM +0900, Josh C. wrote:

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.

I loathe the frameset style of ruby-doc.org for things like Array
documentation. There are too many levels of navigation required to
reach
things sometimes, and lots of back-buttoning when the first guess about
where to find something turns out to be wrong.

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).

I did not know rdoc.info existed. If it’s as complete as you make it
sound, it’s probably going to be my main go-to for Web-based Ruby
documentation from now on. The interface is awesome (now that I know
where to find core). Thanks for mentioning it.

23

On Tue, Aug 2, 2011 at 11:03 PM, Josh C. [email protected]
wrote:

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.

24

On Wed, Aug 3, 2011 at 3:51 AM, Eric H. [email protected] wrote:

In your headers:

List-Help: mailto:[email protected]?body=help

So you email the address with help and get:

You can figure out the range from the archives:

http://blade.nagaokaut.ac.jp/ruby/ruby-talk/index.shtml

Remember, mail ruby-talk-ctl, not ruby-talk

Good idea. Though, if the work has already been done, I’d prefer to
use that, simply since it’ll take ages for me to receive a couple of
thousand messages (Even if it’s ‘just’ the headers to scan the
Subject: line and get the message ID). Been there, done that, burned
the t-shirt in disgust.

Though, I could also scrape Google search results, which would make
things a lot easier, since it’d suppress duplicates (well, most of
them).

Needs some more pondering on my end. :slight_smile:

–
Phillip G.

phgaw.posterous.com | twitter.com/phgaw | gplus.to/phgaw

A method of solution is perfect if we can forsee from the start,
and even prove, that following that method we shall attain our aim.
– Leibniz