From: James Edward Gray II <james@...>
Date: 2006-03-20T01:07:38+09:00
Subject: Re: Core lib clean-up

On Mar 18, 2006, at 10:47 PM, James Britt wrote:

> James Edward Gray II wrote:
>> On Mar 18, 2006, at 7:59 PM, James Britt wrote:
>>> Trans wrote:
>>>
>>>>> Which is a standard library, not a core class.  It shouldn't be in
>>>>> those docs at all.
>>>>
>>>> Thanks. So there are some issue with the docs themselves.
>>>
>>>
>>> One being that people have to know whether something is 'core'  
>>> or  'stdlib' when they look for it.
>> I offered my best idea for an improvement to this some time ago  
>> on  the Ruby Documentation list.  Did you not feel building an  
>> index page  grouped by functionality held any value James?
>
> Please correct me if my recollection is off, but that would have  
> been a manual process, no?  (My apologies if there was a more  
> direct solution and I let it slip off my radar.)

True, it was a manual process, but I see the maintenance as quite low  
and even addressed that in my message.  For the curios, here is what  
I suggested to the ruby-doc list:

> I know there are plans to improve documentation searching, but I  
> think a simple layer of links could greatly improve documentation  
> access.
>
> I don't know about others, but I easily look something up in  
> String, Array, and/or Hash grossly more often than anything else.   
> To me that means they should be easy to reach.  String is currently  
> the worst:
>
> 1.  Go to documentation site.
> 2.  Click Core link.
> 3.  Scroll... a lot.
> 4.  Click String link.
>
> We could easily cut that in half, couldn't we?  If the front page  
> had some handy categorized links:
>
> Data Structures (or whatever)
> Array, Hash, String, Struct
>
> And why stop there?  Separation of the standard lib makes little  
> sense here.  Change the background color of those links, tag them  
> with an icon, or whatever and there's no reason we can't add those  
> too:
>
> Data Structures
> Array, Hash,   OpenStruct,
> Set,   String, Struct
>
> I'm sure I missed a ton.  The above is just meant as an example.
>
> So far, I've just been talking about easy access, but this could  
> address other issues.  For example, Ruby's reflection is terrificly  
> powerful and maybe the best hid feature of the language! <laughs>   
> There are at least three major classes involved.  Quick, name all  
> three without looking...  Ah, why bother.  Let's just add a group:
>
> Data Structures                 Reflection
> Array, Hash,   OpenStruct,      Module, Object, ObjectSpace
> Set,   String, Struct
>
> Again, I'm sure I missed something but you get the idea.
>
> I realize that what I'm suggesting is not easily automated.  For  
> that reason, I've tried to come up what the simplest thing that I  
> feel has potential to really ease access.  Hopefully, maintaining a  
> single page worth of categorized links would be pretty low  
> maintenance.  It only even needs to be checked for new Ruby version  
> releases.  (Isn't that yearly?)  And I hope String will be safely  
> snuggled in the Data Structures category for a few more releases.  :)

James Edward Gray II