Best ways to accelerate Ruby's popularity

[Simon Strandgaard]

I got so inspired by looking at your mockup.. that I decided to make a
mockup for a new ruby-doc.org homepage.
http://aeditor.rubyforge.org/rubydoc/

Wow, I can't tell you how much more I like that than the current
ruby-doc site.
Hehe.


[snip]
The one minor thing I'd propose (other than a titanium body with a
ghettochest for yours truly) is that there be some visual cue that it's
one of the main Ruby sites. Maybe a shared icon in the upper left
corner, or a shared Ruby banner, or something.

Im bad at drawing icons.. maybe one could draw a nice icon for ruby-doc?

Florian Gross has experimented with some backgrounds..
see here:

http://aeditor.rubyforge.org/rubydoc2/

 

[why the lucky stiff]

First of all, alot of your comments are concerned with left vs. right
placement. In my mind, the material on the right is current information
geared toward a swift introduction to Ruby. The stuff on the left is
factual information as well as domain-specific and dated (but important)
websites.

RAA is a notable omission. I was trying to figure out where to add it,
but decided to just post the thing anyway. Play with text in Photoshop
isn't any fun.

First, where are docs? were they outsourced to ruby-doc in toto or
it is my chance to just read the 4 "learn ruby" titles?
And why is "browse handbook" which (if I knew what "the handbook" is) is
supposed to bring me to documentation, separated from the other stuff?

The "handbook" is imaginary at present, just like the mockup.
I'm referring to an online manual which is organized like Python or PHP
documentation. A language reference (one method per page and module
summary pages) which allows user comments.

Just an idea.

I understand this is a mock page, what I mean is that once you go this
route you may end up re-adding lots of the stuff wich is there aty the
moment, again messing up the page.

Well, the idea is that the home page would give precedence to current
information. Hopefully the management of the home page would consist of
an active team which would conduct weekly or monthly reviews of content.
I think we could be more succinct and leave out some information, since
there's no need to be exhaustive on a single page.

Is monetary contribution to Ruby a higher priority than offering a link
to the Rails blog? The team would determine this.

Is offering simultaneous translations feasible and worthwhile? Or
should separate sites be maintained for Japanese, English, and
potentially other offerings?

I never navigate through a menu. I never click all the links on a page.
I haven't even made it through all the links at RubyGarden despite
actively desiring fresh news for RedHanded. I think we can limit the
information presented safely.

Of course, these aren't my decisions to make. And this whole discussion
is rather hypothetical in light of (1) having no Ruby.org, (2) having a
functional Ruby-Lang.org which I am quite grateful for and (3) teamwork
between international parties being as hard as it is anyway.

_why

 

[James Britt]

I don't think the technical issues should be too hard. Apache, at
least, is happy to serve docs from multiple virtual hosts, and something
can be known as say rubyforge.org, www.rubyforge.org and
rubyforge.ruby-lang.org pretty easily.

Serving from the same machine is one thing; servicing requests when the
sites are on physically distinct machines, under separate administrative
control, is another. I don't know enough about Apache to say for sure;
it may be enough to engineer redirects to other sites so that a request
for docs.ruby.org (or whatever) lands you on www.ruby-doc.org.


James

 

[Ilmari Heikkinen]

This conversation is rubbing off. I'm seeing things. Here's a mockup:
<http://redhanded.hobix.com/cult/rubyorgMockup.html>

Things that enter my mind:

* Good job!

* New Ruby users are either beginning programmers or more experienced
programmers. There's the brief elevator-speech intro, the beginner
tutorial, Rails tutorial, and pickaxe book. Could there also be
"switcher"-tutorials, where you're given a quick rundown of main
difference between the language you know and Ruby, with pointers to
further info? And maybe API docs (I know some people who use them to
learn languages )


I know it's just a mockup, but here's some visual design crit anyhow

* The visual design tends to make my eyes gravitate directly to the
panel on the right. I mean, it's strange, but I somehow can't read the
left panel without forcing myself. My eyes just don't stick to it.
Hmm.. might be that it sort of reads as a Google Ads -panel to me, and
my built-in spam filter says "DON'T READ, SKIP SKIP, RED ALERT!" Maybe
if there was a colored background there aswell, or just some eyecatch
graphic (bg-embedded ruby, or such) to meld it into the design

* And, to reiterate: Good job!

 

[James Britt]

Well, couldn't that be done with the ruby-lang.org domain? All we need
is 15 minutes work on DNS and a few ServerAliases. ruby.org would be
ideal, but
the general 'ruby mafia' single domain[0] would still work.

Not exactly what you were looking for, but almost as good.

Yup, and I think that's a good step, but I don't think they should be
added as vhosts until the sites have a more unified look and feel (and
until all the server and domain owners decide it's what they want to do).

Making anything harder than it already is will be the kiss of death.

Site should try to follow basic good layout and navigations standards
(de facto, not de jure) as a matter of general good sense. Maybe some
common themes will evolve over time.

I always come back to google, because I think their design is so good,
but try going there and clicking on "web", "images", "groups", "news",
"froogle".

Each site is different, especially news, but it's clear that you're on a
google site. They all have roughly the same header, the same looking
search bar, etc.

The branding and marketing (which is pretty much the flavor I'm getting
here) is not a bad thing, but something of a side issue.

For example, when I read about people having issues with finding Ruby
documentation, the most common problems are

1) They do not know ruby-doc.org exists.
2) They know about the site, but there are no docs for what they want to do.

Issue one is increasingly rare; most Ruby sites have links to ruby-doc
(and, writing this, I realize I'm been dopier than usual, as ruby-doc
seems to have nary a link to any other Ruby site. Ah well. All is
changing anyway.)

Issue two is more critical, and, all things being equal, needs more
attention. And it is improving every day, but more is always welcome
and needed. People should feel encourage to put up Ruby sites and host
threads, forums, docs, apps, project, cartoons, and what have you.

Official or not.


James

 

[James Britt]

Hehe.

What's striking is that this design does nothing to address the main
problems with ruby-doc.

It's more than cosmetic.

Here's a suggestion: If you do a redesign of the ruby-doc main page, and
it has more than 10% of the same text (and that's pushing it), start over.


James

 

[Eko Budi Setiyo]

Issue two is more critical, and, all things being equal, needs more
attention. And it is improving every day, but more is always welcome
and needed. People should feel encourage to put up Ruby sites and
host threads, forums, docs, apps, project, cartoons, and what have you.

Official or not.


James

I agree with last James statement. People should be encourage to create
"Ruby Site"
I am trying to create my own ruby website also
[http://www.rubytoday.com]] wich is not ready now.
I am i the procces off writing my "own application" using ruby now.
Almost finish but still having some problem with "rubytorrent". Once
everyting is ready I will share it here.
This "rubytoday.com" application will serve the "ruby comunity"

regards
eko

 

[Luke Galea]

As a recent adopter of Ruby I've gone through some of the pain of finding ruby
docs for the uninformed.. and I know it seems stupid but the fact that the
"Core API" and "Std-Lib" aren't on the "Documentation" page on ruby-doc.org
threw me off..

I only found them because of google searches, bookmarked them and later found
out how I was intended to find them..

Well, couldn't that be done with the ruby-lang.org domain? All we need
is 15 minutes work on DNS and a few ServerAliases. ruby.org would be
ideal, but
the general 'ruby mafia' single domain[0] would still work.

Not exactly what you were looking for, but almost as good.

Yup, and I think that's a good step, but I don't think they should be
added as vhosts until the sites have a more unified look and feel (and
until all the server and domain owners decide it's what they want to do).

Making anything harder than it already is will be the kiss of death.

Site should try to follow basic good layout and navigations standards
(de facto, not de jure) as a matter of general good sense. Maybe some
common themes will evolve over time.

I always come back to google, because I think their design is so good,
but try going there and clicking on "web", "images", "groups", "news",
"froogle".

Each site is different, especially news, but it's clear that you're on a
google site. They all have roughly the same header, the same looking
search bar, etc.

The branding and marketing (which is pretty much the flavor I'm getting
here) is not a bad thing, but something of a side issue.

For example, when I read about people having issues with finding Ruby
documentation, the most common problems are

1) They do not know ruby-doc.org exists.
2) They know about the site, but there are no docs for what they want to
do.

Issue one is increasingly rare; most Ruby sites have links to ruby-doc
(and, writing this, I realize I'm been dopier than usual, as ruby-doc
seems to have nary a link to any other Ruby site. Ah well. All is
changing anyway.)

Issue two is more critical, and, all things being equal, needs more
attention. And it is improving every day, but more is always welcome
and needed. People should feel encourage to put up Ruby sites and host
threads, forums, docs, apps, project, cartoons, and what have you.

Official or not.


James

 

[Douglas Livingstone]

As a recent adopter of Ruby I've gone through some of the pain of finding ruby
docs for the uninformed.. and I know it seems stupid but the fact that the
"Core API" and "Std-Lib" aren't on the "Documentation" page on ruby-doc.org
threw me off..

Are there non-frames versions of these pages?

The frames always seem to get in the way to me... and all the
bookmarking problems frames have too...

 

[James Britt]

As a recent adopter of Ruby I've gone through some of the pain of finding ruby
docs for the uninformed.. and I know it seems stupid but the fact that the
"Core API" and "Std-Lib" aren't on the "Documentation" page on ruby-doc.org
threw me off..

Duly noted.

Thanks,

James

 

[James Britt]

Are there non-frames versions of these pages?

The frames always seem to get in the way to me... and all the
bookmarking problems frames have too...

The code comes from rdoc, using the (standard? default?) framed view.

Those doc pages need, among other things, a more linear format, and a
way to easily associate comments and annotations with specific paragraphs.

I really do like how PHP.org does its docs. For example,
http://us2.php.net/manual/hk/function.array-reverse.php

Tells you about the array_revese function, shows user comments that
(ideally) can clarify or correct the docs, and lists the other Array
function.

There doesn't seem to be a way to associate a note with a specific
location on the document (though I can imagine a few ways to do this
with JavaScript), which would be killer.

Here's a "Please Write My Code For Me" request: an app that knows how to
render any given (X)HTML doc (local or via URL), along with a comment
section. With spam protection (hey, just forbid links). With the
option to click anywhere on the main doc and add a virtual post-it or a
footnote comment. (Sorry, but that'll likely be JavaScript, not Ruby.
Well, until the Firefox folks wise up.)

C'mon, you Railers could do this in your sleep.

James

 

[Ilmari Heikkinen]

Re: ruby-doc.org

Is there a way to access a class documentation at a certain method
anchor with an url?
I'm not very clear, maybe this example will be clearer:

http://www.ruby-doc.org/find/Enumerable#map
would go to Enumerable#map anchor on the Enumerable page. And it would
have all the navigation frames there, so it's not a place to get
stranded in.

Reason I'm asking is that I'd like to open the ruby-doc doc page in a
webbrowser with Enumerable.help:map. That is with the IHelp
irb-ri-access library. Is this okay btw, or does it put too much burden
on the site?

If it'd be php.net like docs then it'd be even greater: access docs
_with comments by people who have used it_ from irb, and maybe
contribute your own notes.

If this reads very badly (does), ask and I'll try to explain

 

[Zach Dennis]

Serving from the same machine is one thing; servicing requests when the
sites are on physically distinct machines, under separate administrative
control, is another.

This could be handled at a DNS level:

Add an 'A' record to the dns for ruby-lang.org which points
rubyforge.ruby-lang.org to 66.92.150.242 (or whatever the main ip is).
The only time this becomes an issue is when people switch ISPs or IPs
and don't notify one another.

Or this could be handled at a Web Server level:

Have a virtualhost for rubyforge.ruby-lang.org on the ruby-lang.org
server, and redirect the request to rubyforge.org.

Level of difficulty: 5 - Intermediate Networker / Intermediate Web Admin

Zach

 

[Dick Davies]

Serving from the same machine is one thing; servicing requests when the
sites are on physically distinct machines, under separate administrative
control, is another. I don't know enough about Apache to say for sure;
it may be enough to engineer redirects to other sites so that a request
for docs.ruby.org (or whatever) lands you on www.ruby-doc.org.

Yeah, you could do it with a vhost and mod_rewrite on the main ruby server,
but if you're going to get a new dns record setup, why not point it
at the final destination in the first place?

The advantage here is that if ruby-lang.org goes tits up, the other sites
still work.

I suppose if some people don't have access to their webservers it might be
a problem, but then we could fall back to a rewrite hack on widgets.ruby-lang.org...

w.r.t. the 'common theme' idea, I think having a host which is part of the main
ruby site lets people know you're official. Beyond that it's a bonus (I'm assuming
some people have sweated blood to get their sites just so, and will hand over their
css rollover hack when you prise it from their cold dead hands...)

 

[James Britt]

w.r.t. the 'common theme' idea, I think having a host which is part of the main
ruby site lets people know you're official.

I'm extremely leery of any attempt to consolidate things. It just
raises the barrier to participation.

Anyway, it has been suggested in the past that, for example,
docs.ruby-lang.org redirect to ruby-doc.org. I forget the details, though.

All in all, ease of use for users must be balanced by ease of use for
maintainers, or the users will have less to use.


James

 

[zimba.tm]

I think it's cool to have community-driven websites,
after all it's maintained by people who are motivated and they can have
their own way of working.

An idea is to group the sites in an OSTG-like bar.
( cf. the top of the page on slashdot.org )
This bar would be on every linked site of the bar, so that the
connection between the sites would be more evident.
Also by putting the source on ruby-lang, only this site would have to
be updated if a new website joins the party

Cheers,
zimba

 

[Stephen Kellett]

I don't know how you can quantify its value, but I'd say it definitely
has some. Sure, ruby-lang.org is the first hit when you search for
Ruby using Google, but given that Python's official site is python.org,
and perl's is perl.[com|org], I'm not sure if people would realize that
ruby-lang.org is Ruby's official site.

My experience when I wanted to find the Ruby home page was to try
www.ruby.org and www.ruby.com. When that didn't work I went to google
and was a bit surprised at the strange name that I found - ruby-lang.org

I then did some digging around ruby-lang.org and some other sites before
concluding that ruby-lang.org was the correct site, rather than a site
claiming to be the correct site when it wasn't. Given the domain name I
did wonder.

You don't have to make any effort to remember www.NAME.org or
www.NAME.com but ruby-lang, well you have to file that away as something
to remember, the -lang is not obvious, at all.

Does this have much to do with language adoption? I don't think so. Ruby
will stand or fall on its own merits. Dr Dobbs had an article on Ruby
this month in their web services section. Thats a step in the right
direction - although the 'D' language had a mention years ago and look
how well that has been adopted

Does it have much to do with making info easy to find? Absolutely.

In case you think the reason I was confused about ruby-lang.org is
because I'm new to software/internet etc. I'm not, I've been writing
software since 1981, starting with 6502 assembler on a VIC-20. I was
confused because the domain name is not obvious/what you expect.

Stephen

 

[Stephen Kellett]

Did you factor making love into that? Titanium is rather hard...

 

[Stephen Kellett]

Florian Gross has experimented with some backgrounds..
see here:

http://aeditor.rubyforge.org/rubydoc2/

Nice, but for anyone with vision impairment a total nightmare. My vision
is OK, but I'm involved with a vision impairment project and they would
not thank you for those backgrounds.

 

[James Britt]

Re: ruby-doc.org

Is there a way to access a class documentation at a certain method
anchor with an url?
I'm not very clear, maybe this example will be clearer:

http://www.ruby-doc.org/find/Enumerable#map
would go to Enumerable#map anchor on the Enumerable page. And it would
have all the navigation frames there, so it's not a place to get
stranded in.

Not at the moment. Those doc pages are generated from rdoc, and the
anchors to method names a re abstract strings, not the method names
themselves. So you get this:

http://www.ruby-doc.org/core/classes/Enumerable.html#M001864

You need to know that M001864 is the 'map' method.


Now, there is an alternative:

http://www.ruby-doc.org/find/pickaxe/Enumerable#map

though this is calling into an HTML version of the first edition of
Programming Ruby, by Dave Thomas and Andy Hunt. It is not the most
current documentation.

(There was a similar URL look-up system for ri, but it relied on the XML
formatting option that apparently has been removed from the current
ri, and I haven't managed to fix this yet.)

Reason I'm asking is that I'd like to open the ruby-doc doc page in a
webbrowser with Enumerable.help:map. That is with the IHelp
irb-ri-access library. Is this okay btw, or does it put too much burden
on the site?

Depends. How often would there be requests, and by how many people?
Put another way, how does this differ from people viewing the pages
directly in a browser to help them while coding?

I don't see a problem. In general, I like the idea of serving up data
services for remote applications, though in practice I would have to see
how the bandwidth goes if ruby-doc had a more direct Web API for
accessing documentation. (Though the data format should be something
other than HTML 4.)

If it'd be php.net like docs then it'd be even greater: access docs
_with comments by people who have used it_ from irb, and maybe
contribute your own notes.

I would like that, and have taken some stabs at writing a wrapper that
would allow comments on arbitrary HTML pages, but have gotten
sidetracked by numerous other projects.

If this reads very badly (does), ask and I'll try to explain

No, I think I understand. It is a problem that one cannot easily locate
and/or bookmark specific methods and classes. The framed view of the
docs is handy for certain things, but not others. And allowing comments
on the docs would be sweet.

It is yet another item on my "This has been taking forever" ruby-doc
rewrite.


James