From: Phillip Gawlowski <cmdjackryan@...>
Date: 2011-08-06T03:54:54+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

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.


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