> 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.
···
On Sat, Aug 06, 2011 at 05:03:39AM +0900, Andy Davis wrote:
--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]
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.
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.
···
On Aug 6, 2011, at 1:28 PM, Chad Perrin wrote:
On Sun, Aug 07, 2011 at 04:39:16AM +0900, Eric Hodel wrote:
On Aug 5, 2011, at 7:05 PM, Chad Perrin wrote: