Brainstorming ideas how to improve Ruby's documentation

Ruby
21

On Fri, Aug 5, 2011 at 8:44 PM, Andy D. [email protected] 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.

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

–
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

22

On Fri, Aug 5, 2011 at 10:32 PM, Eric W. [email protected]
wrote:

While I’m bikeshedding, I do wish RDoc didn’t use icons/JS at all. The
The only useful tags in HTML to me are , and 

 :slight_smile:

The class of tags is useful too (semantic markup!), as is the

for tabular data.

However, I don’t think I’m representative of the Ruby community at
large.

Nope, I prefer a lack of JS, frames, and nonsense like that, too.

–
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

23

On Fri, Aug 5, 2011 at 02:48, Marc H. [email protected]
wrote:

We need NEW ideas and for this to happen some OLD ideas must die.

Agree on the general point.

I think you are using the wrong reference, though.

If you want to compare to an excellent documentation implementation,
look at Perl.

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

And so on…

(For those among you cringing at the idea of a command line, there are
web pages with this, e.g.

http://perldoc.perl.org/
http://perldoc.perl.org/POSIX.html
http://perldoc.perl.org/Test/More.html
http://perldoc.perl.org/perlre.html
http://search.cpan.org/~mschwern/Test-Simple-0.98/lib/Test/More.pm)

I think there are two sides to this:

  1. Perl’s community has a tradition of NOT documenting isolated
    functions, but documenting modules. I guess you could fix this by
    providing better tools.

  2. Perl’s community appreciates Perl’s documentation a lot, so module
    authors do write good documentation. This needs a change in attitude.

Marcelo

24

Marc H. [email protected] wrote:

If you do not believe me, click on it:

RDoc Documentation

There you have it. HTML Frames in all their ugly glory.

I hate frames, too, but I find the non-frame Darkfish layout
in RDoc 2/3.x very usable with lynx and Vimperator (firefox).

Darkfish is even usable without JavaScript[1]. In fact, I don’t think
I’d have halfway usable websites for my Ruby projects without
Darkfish.

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

While I’m bikeshedding, I do wish RDoc didn’t use icons/JS at all. The
The only useful tags in HTML to me are , and 

 :slight_smile:

However, I don’t think I’m representative of the Ruby community at

large.


[1] I wrote wrongdoc to strip JS from all the RDoc I upload to

bogomips.org: wrongdoc - RDoc done wrong

I couldn’t get alignment to work right w/o icons, though…
25

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

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

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

26

On Sat, Aug 06, 2011 at 05:03:39AM +0900, Andy D. wrote:

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.

It seems like you’re talking about linking internally, between parts of
the documentation, while the problem brought up is the fact that if you
just copy the URI out of your browser’s address bar and link to that
from
another site or in an email you’ll end up with a link to the frameset
with default pages open in the frames rather than a link to the
particular page to which you intended to direct someone.

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.

On the other hand, you can make a page look better, and design it to be
more easily and intuitively navigable, without frames – and once you do
that, you might as well not offer the frames option alongside the
non-frames option.

27

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

28

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

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

29

On Fri, Aug 5, 2011 at 5:49 AM, Phillip G.
[email protected]
wrote:

Thank you. I was becoming concerned with how many people seem to think
they
are the same thing.

On Fri, Aug 5, 2011 at 5:54 AM, Fred L. [email protected] wrote:

I do that. I have gmail automatically tag them and remove them from my
inbox. Then I just go check the tag every now and then, and see what’s
new.

On Fri, Aug 5, 2011 at 7:47 AM, Keith B.
[email protected]wrote:

I don’t understand what you mean when you say “And totally unusable as well
by the way.” – how is it unusable? And how is the Pickaxe book ready for
retirement? It’s an outstanding reference, and I’m often consulting it.

I agree, I prefer the ruby-doc style docs (though I’ve never figured out
why
they list the files). And I also agree that the Pickaxe is probably the
best
Ruby book there is. I think they could do with removing the API that
takes
up a few hundred pages, but man, there is some really great stuff in
there. Not just API things, but intermediate things like how to
structure
your programs, and even extremely advanced things like how to wrap a C
library with Ruby. I wish I had read it long before I did (I was put
off by
it’s 1000 pages).

30

On Aug 5, 2011, at 7:05 PM, Chad P. 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

31

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

On Aug 5, 2011, at 7:05 PM, Chad P. 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

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

32

On Aug 5, 2011, at 7:05 PM, Chad P. [email protected] wrote:

$ 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

33

On Fri, Aug 5, 2011 at 2:27 AM, Alexander Litvinovsky
[email protected] wrote:

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

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

–

Alex C. - [email protected] - http://alexch.github.com
Stalk me: Redirecting... | http://twitter.com/alexch |
http://alexch.tumblr.com

34

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

35

On Sun, Aug 7, 2011 at 7:52 PM, Alexey P. [email protected]
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

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

36

On Aug 7, 2011, at 14:42 , Alex C. 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.)

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

37

Actually I’m very glad to see this topic, the fame of Rails is powerful
catalyst, but it can’t do all the marketing for Ruby alone.

I believe it’s important to constantly improve and constantly move in
the future and have the courage to drop some outdated luggage from the
past.
Especially now when there’s so attractive solutions like Node.js.

But, the intention in this topic looks like a demand, I think that we
shouldn’t demand something from the core team, but instead try to create
alternatives by themselves (not only docs, all aspects of ruby, and I
very glad to see emergence of things like JRuby and Rubinius ).

P.S.
After writing that I realized that this time I demand to do something
from You. So, I decided that my demand is also wrong and at first I
should do something by myself.

So, I build up the documentation site with alternative style (using
sdoc) for ruby - http://ruby-doc.info

sources https://github.com/alexeypetrushin/ruby-doc

38

On Aug 6, 2011, at 1:28 PM, Chad P. wrote:

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

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.

For Ruby 1.9.3 I wrote explanatory text for OpenSSL and a second
contributor and I worked together to provide better explanatory text for
Net::HTTP. There were a couple patches I applied to add better
explanatory text to various parts of the standard library.

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

If we’re missing it then provide a patch, even if that means contacting
an author and asking to make a contribution based on their work.

39

On Aug 7, 2011, at 5:52 PM, Alexey P. 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

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

40

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

[…]
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.