Brainstorming ideas how to improve Ruby's documentation

ruby-talk
21

we need a list of requirements as to what will make for a successful
documentation effort. I have been working off list on finding a
suitable domain name. While ruby-lang.org/en/docs/ would work, imho, a
site dedicated to updated documentation would be better.

I propose that one chance we have to one up the competition would be
to have the examples executable with a reset option.
I would be more than happy to integrate this into TryRuby (yes updates
are coming, that's a different thread).
In this manner you could literally play with with and modify the
example code in the documentation and reset it to see the original.

Would copying the perldocs style format and writing standard, just to
get this effort underway be sufficient? What do you all ( the ruby
community) not like about the perldocs? It seems like they have it
going on. I would focus primarily on a website with PDF output version
of the docs first and manpage style docs secondary.

What it sounds like what we really need is standardization in how
documentation is written. We programmers are use to the idea of Coding
Standards. Perhaps we now need a Technical Writing Standard for ruby
docs? I don't want to turn this into some ITIL inspired garbage, but
some sort of writing standard agreement would be helpful here.

Respectfully,
Andrew McElroy
http://TryRuby.org

···

On Sun, Aug 7, 2011 at 7:52 PM, Alexey Petrushin <axyd80@gmail.com> wrote:

Text itself is fine, but I agreed, RDoc output is ugly and unusable

Why can't it be like this http://railsapi.com/doc/ruby-v1.9.2

22

It's hard to link into frames. Here is a link to the documentation of OpenSSL::X509::Name::new:

http://railsapi.com/doc/ruby-v1.9.2/classes/OpenSSL/X509/Name.html#M006274

How do I get to the top-level OpenSSL documentation? Where is the navigation sidebar?

Links to external sites end up wrapped in nonsensical navigation from the frame. From the main page go to Net::HTTP then click the link to http://www.ietf.org/rfc/rfc2616.txt\.

While both of these problems with frames are solvable, nobody has bothered to.

If you want RDoc to have a different template that is not "ugly" by default then please write and popularize it. I probably won't accept one using frames, though. (The same page layout features can be accomplished in modern browsers through CSS.)

···

On Aug 7, 2011, at 5:52 PM, Alexey Petrushin wrote:

Text itself is fine, but I agreed, RDoc output is ugly and unusable

Why can't it be like this http://railsapi.com/doc/ruby-v1.9.2

23

SOOOO much better. I've added this to hoe. Thanks for the tip.

BTW... we'll also make it so that rdoc supports this properly. It's just quicker to iterate on hoe.

···

On Aug 5, 2011, at 13:32 , Eric Wong wrote:

One (important (to me)) thing I do with my RDoc + Darkfish sites is
remove the default index.html and and replace it with the HTML for
README, leading to an index column on the left.

Contrast the following two, I prefer the latter to be the default
index page:

  http://rdoc.rubyforge.org/index.html
  http://rdoc.rubyforge.org/README_txt.html

24

I think you replied to the wrong guy. I didn't rag on RDoc for not
producing tutorials. I think Marc Heiler might feel like the presence of
RDoc makes people think they don't need to write tutorials, though, thus
providing a social impediment to the development of good tutorials.

By the way -- is there any chance you could avoid TOFU [1] posting in the
future?

[1]: http://tinyurl.com/3tghtnt

···

On Fri, Aug 05, 2011 at 06:56:16PM +0900, Chris Kottom wrote:

I think you can't really rag on RDoc for not producing tutorials. That
would be like me getting mad at my fridge over the quality of the toast it
produced - wrong tool for the job.

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

25

Alexander Litvinovsky wrote in post #1015099:

What are you talking about? Ruby has a nice docs, railsapi.com for
example.

2011/8/5 Fred L. <;;;;;;;;;;;;>

Was it necessary to post a reply with my mail address in it ..!!!???

can someone please edit it..?

···

--
Posted via http://www.ruby-forum.com/\.

26

They are a usability and accessibility nightmare.

Can you elaborate? The ruby documents --RDoc and the stdlib-- are in
frames. It sounds like the document masters wouldn't agree.

Personally speaking, I've yet to find any documentation as well packaged
and accessible as the javadocs. Ruby docs aren't bad, but my preference
is the javadoc style.

There's a reason the
W3C recommends *against* using frames (in fact, HMTL5 was supposed to
remove frames altogether).

What reason would that be? I tend to agree that web sites that use
frames tend to be a bit ugly and difficult to use. But this pertains to
documentation, where the divide and conquer approach is very helpful.
Frames do serve a purpose, but maybe not for you.

···

--
Posted via http://www.ruby-forum.com/\.

27

There's a crapton of stuff in perldoc that doesn't have an equivalent in
ri, though.

···

On Sat, Aug 06, 2011 at 10:07:33AM +0900, Ryan Davis wrote:

On Aug 5, 2011, at 13:42 , Marcelo wrote:
>
> Perl's killer feature is its documentation, IMO.
>
> $ perldoc POSIX
> $ perldoc LWP
> $ perldoc Test::More
> $ perldoc -f print
> $ perldoc -f open
> $ perldoc perlre
> $ perldoc perllol

ri String
ri String.split
etc

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

28

I think you just made the case that Ruby *doesn't* have nice docs. If
people have to go to a site called "railsapi" to get the *ruby* api
then something is wrong. :slight_smile:

FWIW, I pretty much agree with Marc Heiler... although I have to say
his post crossed the line from passionate to obnoxious.

Whenever I teach Ruby (which I've been doing a lot lately) I have to
tell a too complicated story about docs. There are some pretty big
problems with the state of Ruby Docs, and they go beyond frames and
searchability. Here's a list off the top of my head.

...and before you read the list, I hope you don't think I'm whining!
I'm pointing out specific problems with specific tools and information
designs, and I'd be happy to help fix some of them if I can (and if I
get support from key core members).

http://www.ruby-doc.org is hard to use -- the front page has TMI,
RDoc Documentation doesn't cross-link to
RDoc Documentation , there's no clear "read this then
that" path...

There are several web sites that make ruby API docs searchable and
better organized, e.g. http://railsapi.com/ and http://gotapi.com.
However, they don't fix some of the core problems of rdoc. Even
without frames (darkfish ftw!) rdoc makes too many words hyperlinks to
the wrong pages, it has unmemorable and randomly changing anchor link
names, it often links to a page describing a *file* instead of the
documented *class* inside that file, and more.

Documentation has a whole bunch of links
to other sites; again it feels like information overload.

For command-line docs, ri works pretty well, but the ri db is not
installed by rvm (!!!), and many people ritually install gems with
--no-ri --no-rdoc because generating the documentation often makes the
install take 3x as long (and the whole world has ADHD these days so 3x
is unacceptable).

(By the way, would it be so horrible if "gem install" forked off a
process to build the docs in the background? On systems that support
fork, of course.)

···

On Fri, Aug 5, 2011 at 2:27 AM, Alexander Litvinovsky <alexander.litvinovsky@gmail.com> wrote:

What are you talking about? Ruby has a nice docs, railsapi.com for example.

--

Alex Chaffee - alex@cohuman.com - http://alexch.github.com
Stalk me: Facebook | http://twitter.com/alexch |
http://alexch.tumblr.com

29

Ruby Forum is an interface to the ruby-talk mailing list. Your email address
is public whenever you post:
http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/386240

The archives are at http://blade.nagaokaut.ac.jp/ruby/ruby-talk/index.shtml

···

On Fri, Aug 5, 2011 at 11:07 AM, Fred L. <f.linard@fdtec.net> wrote:

Was it necessary to post a reply with my mail address in it ..!!!???

can someone please edit it..?

30

They are a usability and accessibility nightmare.

Can you elaborate? The ruby documents --RDoc and the stdlib-- are in
frames. It sounds like the document masters wouldn't agree.

Browse to the Ruby standard library with a non-frames, text-only
browser. Screen readers don't do a much better job of parsing frames.
And consider the linking nightmare.

And the RDoc generated documentation is in frame form because that's
how RDoc originally outputted docs.

There's a reason the
W3C recommends *against* using frames (in fact, HMTL5 was supposed to
remove frames altogether).

What reason would that be?

Accessibility and usability. And frames break linking, and page navigation.

I tend to agree that web sites that use
frames tend to be a bit ugly and difficult to use. But this pertains to
documentation, where the divide and conquer approach is very helpful.

That's what menus, in-page anchors and page crumbs can provide, too.

Frames do serve a purpose, but maybe not for you.

"If all you have is a hammer, every problem looks like a nail."

···

On Fri, Aug 5, 2011 at 8:44 PM, Andy Davis <ananonana@gmail.com> wrote:

--
Phillip Gawlowski

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

31

Perl's killer feature is its documentation, IMO.

$ perldoc POSIX
$ perldoc LWP
$ perldoc Test::More
$ perldoc -f print
$ perldoc -f open
$ perldoc perlre
$ perldoc perllol

ri String
ri String.split
etc

There's a crapton of stuff in perldoc that doesn't have an equivalent in
ri, though.

Patches welcome

···

On Aug 5, 2011, at 7:05 PM, Chad Perrin <code@apotheon.net> wrote:

On Sat, Aug 06, 2011 at 10:07:33AM +0900, Ryan Davis wrote:

On Aug 5, 2011, at 13:42 , Marcelo wrote:

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

32

Ruby 1.9.3 is over 65% documented while Ruby 1.9.2 was under 55% documented. This increase was due to contributions from the community after my documentation challenge. If there's stuff you'd like documented please contribute:

http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge

···

On Aug 5, 2011, at 7:05 PM, Chad Perrin wrote:

There's a crapton of stuff in perldoc that doesn't have an equivalent in
ri, though.

33

File a ticket please. I think that's a fine compromise.

···

On Aug 7, 2011, at 14:42 , Alex Chaffee wrote:

(By the way, would it be so horrible if "gem install" forked off a
process to build the docs in the background? On systems that support
fork, of course.)

34

[…]
However, they don't fix some of the core problems of rdoc. Even
without frames (darkfish ftw!) rdoc makes too many words hyperlinks to
the wrong pages,

By default RDoc hyperlinks things that look like methods, words like foo_bar. I think it's still occasionally overzealous when you have commonly-named classes but I'm unsure how to make it less eager yet.

it has unmemorable and randomly changing anchor link
names,

This no longer happens. Example:

http://docs.seattlerb.org/minitest/MiniTest/Assertions.html#method-i-assert_empty

it often links to a page describing a *file* instead of the
documented *class* inside that file

Please show me an example, this shouldn't happen unless you have .rb or .txt on the end.

For command-line docs, ri works pretty well, but the ri db is not
installed by rvm (:bangbang:!)

Run rvm docs generate

and many people ritually install gems with
--no-ri --no-rdoc because generating the documentation often makes the
install take 3x as long (and the whole world has ADHD these days so 3x
is unacceptable).

(By the way, would it be so horrible if "gem install" forked off a
process to build the docs in the background? On systems that support
fork, of course.)

We're working on improving this some in RubyGems 1.9 and forward, but that effort has been stalled while we fix bugs for Ruby 1.9.3.

···

On Aug 7, 2011, at 2:42 PM, Alex Chaffee wrote:

35

Adam Prescott wrote in post #1015112:

Ruby Forum is an interface to the ruby-talk mailing list. Your email
address is public whenever you post...

well 'public' for the list members... but not clearly visible online.
by including my mail address in the reply, it's visible online here

wher I see it, because I'm using this interface and not the mailing
list.

but by the way, why delete all my post, and just keep my mail address
included ???

···

--
Posted via http://www.ruby-forum.com/\.

36

Browse to the Ruby standard library with a non-frames, text-only
browser. Screen readers don't do a much better job of parsing frames.
And consider the linking nightmare.

Maybe I'm missing something, but the linking nightmare you mention can
easily be resolved with a script. Isn't that their purpose -- to
automate the most mundane and easily-botched of routines? Unless you're
hand-coding the files, I don't see why this is so difficult.

For people with eyesight problems I can understand using text-only
browsers (and certainly screen readers), but the solution need not be
one-approach only. One script can generate frames (or menus), and
another can generate text-only pages. Just because frames do not
address every problem does not mean they are invalid.

And the RDoc generated documentation is in frame form because that's
how RDoc originally outputted docs.

That still doesn't negate the fact that someone found frames useful at
some point.

Frames do serve a purpose, but maybe not for you.

"If all you have is a hammer, every problem looks like a nail."

You're stating an unwarranted extrapolation. I never said frames were
the right solution for everyone. I said that it has worked splendidly
for me in the past, and that I would recommend a similar style for Ruby
docs. Again, the solution need to be comprised of a singular approach.

···

--
Posted via http://www.ruby-forum.com/\.

37

Yup, and this is one of the reasons why RDoc hasn't shipped with a way to generate HTML frames in years.

···

On Aug 5, 2011, at 11:54 AM, Phillip Gawlowski wrote:

On Fri, Aug 5, 2011 at 8:44 PM, Andy Davis <ananonana@gmail.com> wrote:

They are a usability and accessibility nightmare.

Can you elaborate? The ruby documents --RDoc and the stdlib-- are in
frames. It sounds like the document masters wouldn't agree.

Browse to the Ruby standard library with a non-frames, text-only
browser. Screen readers don't do a much better job of parsing frames.
And consider the linking nightmare.

And the RDoc generated documentation is in frame form because that's
how RDoc originally outputted docs.

38

When I say there's a crapton of stuff in perldoc that doesn't have an
equivalent, I'm not talking about the percentage of the language's API
that has basic argument, return value, data type and minimal syntax
documentation. I'm talking about the explanatory text that comes in many
of the special perldoc pages. It gives a deeper understanding of the way
things work in the language through lucid, extensive descriptions of how
things work, in a way that does not exist in the Ruby world as far as
I've seen apart from short articles and tutorials scattered around the
Web and a number of excellent books.

. . . and that, really, is Ruby's documentation strength: the community
is overflowing with authors who have written and published really
excellent books (though ri is nice for what it is, too).

···

On Sun, Aug 07, 2011 at 04:39:16AM +0900, Eric Hodel wrote:

On Aug 5, 2011, at 7:05 PM, Chad Perrin wrote:
> There's a crapton of stuff in perldoc that doesn't have an equivalent in
> ri, though.

Ruby 1.9.3 is over 65% documented while Ruby 1.9.2 was under 55%
documented. This increase was due to contributions from the community
after my documentation challenge. If there's stuff you'd like
documented please contribute:

http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

39

By default RDoc hyperlinks things that look like methods, words like foo_bar. I think it's still occasionally overzealous when you have commonly-named classes but I'm unsure how to make it less eager yet.

Yeah, it's a sticky problem, I admit. In general I'd say to err on the
side of being conservative, though I'm not quite sure what that means
in practice.

One example is that, at least before, class names inside code blocks
were enlinkenated. That seems to have stopped recently; not sure if
it's rdoc or darkfish or what that corrected it.

it has unmemorable and randomly changing anchor link
names,

This no longer happens. Example:

http://docs.seattlerb.org/minitest/MiniTest/Assertions.html#method-i-assert_empty

Yay!

it often links to a page describing a *file* instead of the
documented *class* inside that file

Please show me an example, this shouldn't happen unless you have .rb or .txt on the end.

With darkfish, the first thing the user sees on the left side is a
list of file names. Clicking on those gives a page (actually I think
it's a lightbox, but same diff) with no info and no links to the
classes/modules defined inside that file.

e.g. from http://erector.rubyforge.org/rdoc/Erector.html click on
"abstract_widget.rb". You see a big bunch o' nothin', not even a link
to http://erector.rubyforge.org/rdoc/Erector/AbstractWidget.html which
is what you wanted/expected when you clicked on "abstract_widget".

For command-line docs, ri works pretty well, but the ri db is not
installed by rvm (:bangbang:!)

Run rvm docs generate

Yeah, I know, but most people don't do this step (see ADHD note).

We're working on improving this some in RubyGems 1.9 and forward, but that effort has been stalled while we fix bugs for Ruby 1.9.3.

Keep up the good work!

- A

···

--

Alex Chaffee - alex@cohuman.com - http://alexch.github.com
Stalk me: Facebook | http://twitter.com/alexch |
http://alexch.tumblr.com

40

If you are talking about Alexander Litvinovsky post where he said
"What are you talking about? Ruby has a nice docs, railsapi.com for
example." he included the whole of your message as was sent to the
list, it was just the forum that truncated it.

Also try googling this "What are you talking about? Ruby has a nice
docs, railsapi.com for example.", the third result is this list. If
it's on Google then its about as public as it can get. This post will
probably be there within a few minutes of me posting it.