Best ways to accelerate Ruby's popularity

[Ben Giddings]

What is the "it" that would all be on the same machine? The DNS
configuration, or the sites themselves? Or both?

Sorry, I wasn't clear. The DNS configuration would be on whatever
machine handles DNS for the ruby-lang.org domain, (often a site at the
registrar).

The web site and its configuration files would all be on a separate
machine (whatever ruby-doc.org, for example, is on now). What I was
getting at was that the current ruby-lang.org web server wouldn't be
involved at all.

Ben

 

[James Britt]

I can't quite figure out where you stand from these comments.

I think that despite the fact that a common "look" would not solve the
problem determining a site's reliability, it *will* (as you said) reduce
confusion. For me, this is a big issue and should be done.

Generally speaking, a common look can reduce confusion, to some degree.
For example, if I'm clicking around a site, and the style suddenly
changes, I may think I've gone to another site.

If a number if sites have a similar look and feel, I will probably
assume the have some bond. But there is nothing to stop anyone from
exploiting this conferred trust by making a site that looks just like an
"official" Ruby site.

(If there was a registered trade mark or service mark for Ruby(tm) and
"The Ruby Look", then perhaps one could bring a lawsuit. I consider
that unlikely.)

Improving the reliability, content, and organization of various sites is
also important and should be done.

Agreed, and, as you noted, a separate matter from any notions of making
selected sites look or be "official."

Improving the reliability, content, and organization requires a good
understanding of who is using the site and what they come to accomplish,
and providing for this in such a way that the care and feeding of the
site is not an undue burden.

Most of the discussion so far seems more focus on branding and personal
color preferences than on any sort of information architecture.

Trust and authority are certainly elements of a user's concerns, but I'm
skeptical that these are among the main issues, for most users, with the
current set of Ruby sites.


James

 

[James Britt]

Sorry, I wasn't clear. The DNS configuration would be on whatever
machine handles DNS for the ruby-lang.org domain, (often a site at the
registrar).

The web site and its configuration files would all be on a separate
machine (whatever ruby-doc.org, for example, is on now). What I was
getting at was that the current ruby-lang.org web server wouldn't be
involved at all.

Ah, that's sounds interesting.

Thanks,

James

 

[Douglas Livingstone]

Trust tends to come from a network effect. If I determine one site to

be trustworthy (say, ruby-lang.org), and it links to another site
(rubyforge.org), I can infer that that other site is probably worthwhile.

True, branding and linking are both things which are important. The
network effect is reduced when it feels like you are moving from one
network to another - there is no link on the ruby-lang.org front page
to ruby-doc.org. Instead, ruby-doc is listed on the "Downloadable
documents" page. The network effect is active here too: above
ruby-doc, there is a link to Ruby 1.4.6 documentation, and a notice
that the "reference manual for Ruby 1.6 is not yet prepared", while on
the front page there is a download link for Ruby 1.8.2! Does this mean
that ruby-doc is more out of date than either of those two?

I don't see any shortcuts for people to figure out what sites are
reliable sources and which aren't. A stamp of approval won't do it.

You are right, naturally, putting a stamp on something doesn't make
the contents more correct. OTOH, the new user doesn't know what
"correct" is - the only way they can tell is by perception of value.
To increase the perceived value, you need the positive networking and
visual harmony.

Removing dead links on the ruby-lang site would be a good first step.

On: http://www.ruby-lang.org/en/20020103.html

The link to "Ruby 1.4 Reference Manual" gives a "Not Found" error
The link to "The article in Dr. Dobb's Journal Jan. 2001" says "We are
updating our site's registration system."
The link to "The web page for Dave and Andy's book " is "does not
exist on this server."
"Dr. Dobb's Journal Jan. 2001: Programming in Ruby" is repeated, and
still doesn't work
The link "InformIT: The Ruby Programming Language " says "Error 404 -
Page Not Found"
"IBM DeveloperWorks: Ruby: An open source gem from Japan" says "Our apologies"
"SunWorld Online Jan. 2000" says something about Unix, I don't see
anything on Ruby
"SunWorld Online Feb. 1999 " is the same Unix page, still nothing on Ruby

On the menu on the left, if you click "What's Ruby?" then "Matz's
presentation at JAOO" you end up at
"http://www.ruby-lang.org/en/20010919.html"

The link to the "Slides" says "Not Found"

Again, on the menu, when you click "Ruby's License" you get sent to a
text file. It would be nice if there was at least warning that it was
a text file, rather than an integral part of the site. Perhaps a "this
is what you can do under the Ruby licence in human language" page,
with a link to the "real" licence would probably be more useful for
common people. (See what the creative commons people are doing, and
the multitude of sites explaining the GPL.)

That's just the start - I've not even gotten onto the visual cohesion
problems between sites. You are right, a stamp of approval won't do
it. We need something to put the stamp on first.

Douglas

 

[Douglas Livingstone]

On: http://www.ruby-lang.org/en/20020103.html

Quoting my own message, but that link in itself is a problem. At first
glance, it doesn't say anything about what is on the page, only that
it was made three years ago so cross you fingers it is still up to
date. We need friendly URLs like the ones Rails uses.

Douglas

 

[Douglas Livingstone]

For example, if I'm clicking around a site, and the style suddenly

changes, I may think I've gone to another site.

Which is what is happening at the moment, lots of sites which are hard
for a new user to keep track of.

But there is nothing to stop anyone from exploiting this conferred trust
by making a site that looks just like an "official" Ruby site.

This argument applies to banks, not manuals.

look or be "official."

Would it be right to say that you are more against having a
distinction between "official" and "unofficial" web sites rather than
against the idea of bringing the documentation available closer
together?

Trust and authority are certainly elements of a user's concerns, but I'm
skeptical that these are among the main issues, for most users, with the
current set of Ruby sites.

Less "authority" and more "confidence". I can't talk for mst users,
but for me I'd like the confidence to say "That there is the Ruby
documentation." That is a main issue. Can't we apply the "fun to use"
principle to the documentation *and* the language itself?

Douglas

 

[James Britt]

Less "authority" and more "confidence". I can't talk for mst users,
but for me I'd like the confidence to say "That there is the Ruby
documentation." That is a main issue.

I have to say this is the first time I've ever heard anyway suggest that
they could not tell that the docs at ruby-doc.org were the actual Ruby
documentation.

Can't we apply the "fun to use"
principle to the documentation *and* the language itself?

Yes. Why do you ask?

James

 

[James Britt]

True, branding and linking are both things which are important. The
network effect is reduced when it feels like you are moving from one
network to another - there is no link on the ruby-lang.org front page
to ruby-doc.org. Instead, ruby-doc is listed on the "Downloadable
documents" page. The network effect is active here too: above
ruby-doc, there is a link to Ruby 1.4.6 documentation, and a notice
that the "reference manual for Ruby 1.6 is not yet prepared", while on
the front page there is a download link for Ruby 1.8.2! Does this mean
that ruby-doc is more out of date than either of those two?

Good points, though nothing that will be solved by re-styling a page.

Should the link to ruby-doc be on the main page? I can't say, because
the main page could probably be better organized overall, and that
organization depends on identifying what goals the site means to serve,
and then it can be determined what links go where.

(Offhand, I think the ruby-lang main page needs a prominent link to a
"Documentation" page, and that page should directly host the core and
stand lib API docs. And there should be link to ruby-doc, where one can
go for more documentation on a broader range of Ruby topics.)

You are right, naturally, putting a stamp on something doesn't make
the contents more correct. OTOH, the new user doesn't know what
"correct" is - the only way they can tell is by perception of value.
To increase the perceived value, you need the positive networking and
visual harmony.

The networking, yes, but the visual harmony is a red herring. If the
ruby-lang site says, "Go here to see active Ruby projects", then it's
pretty clear it's related and valuable.

Removing dead links on the ruby-lang site would be a good first step.

On: http://www.ruby-lang.org/en/20020103.html

<snip/>

I big problem I've run into trying to keep ruby-doc up to date is the
steady increase in Ruby resources. I've given up trying to manually
track and add them, and have some beta ruby-doc code to do it for me.

But before anyone sets out to update the links on ruby-lang, it may be
worth asking if a) this sort of content even belongs there, and b) if
so, how can it be arranged so that keeping up doesn't become a
full-time job?

A really big advantage to making it easier for people to create Ruby
sites (and part of this is not discouraging interest because a site may
be considered "unofficial") is that you can offload the work. Why
manually update a set of "In the news" links on ruby-lang when you can
just grab and cache RSS feeds from trusted sources? Let others write
the content, on their time, on their machines, in a manner that works
for them.

An a side note, perhaps I'm misreading things, but this thread seems
strongly focused on new users. The discussion on how to re-do various
Web sites seem to argue that the sites need to focus on the needs of
newbies.

Certainly newcomers should be afforded every convenience, but they are
not the majority audience, and newbies won't stay newbies for long.

There is a certain style of usability design that makes things really
easy to do something the first time, but becomes increasingly annoying
as one acquires more experience and all the newbie features just get in
the way.

It is not easy to find the right balance, and people ought not be thrust
into "expert mode" right off the bat, but I suspect that many things
that may one thinks of as valuable to a newcomer will quickly strike
them as just more stuff taking up screen space as they soon get more
familiar with a site.

James

 

[Douglas Livingstone]

I have to say this is the first time I've ever heard anyway suggest that
they could not tell that the docs at ruby-doc.org were the actual Ruby
documentation.

I guess you're starting to get a new type of visitor then

When I first saw it, it felt like a dumping ground for odd bits of
documentation which didn't have a proper home... like it was some sort
of archive, and the real documentation was somewhere else yet to be
found.

It feels like it is designed to be as hard to read as possible. The
front page has mile long lines of text, random bits of news which
belong on ruby-lang, a Ruby Directory's worth of links stuffed into a
right hand column, bits of text lying around saying to join the
mailing list, each item on the menu seems to take you to a totally
different site, no way to search, no menu to browse, frames every
second page so you can't share links with other people... I don't
know. I can't look at it for more than about 5 minutes, does my head
in.

At least the Pragmatic Guide is easy to read (well, the version without frames).

A bit harsh, but honest.

Yes. Why do you ask?

Because ruby-doc.org is not fun to use

Douglas

 

[Trevor Wennblom]

Because ruby-doc.org is not fun to use

Agreed. I regularly prefer the Ruby documentation in the Pragmatic book
over any other source.

 

[James Britt]

Because ruby-doc.org is not fun to use

Well, there ya go.

I appreciate your offering your opinion on this, and agree with some of
your points.

I also hope others speak up on what the do or don't like; I've asked
this on previous occasions, but typically get very little response, so
it is hard to tell what works and what doesn't.

James

 

[Douglas Livingstone]

organization depends on identifying what goals the site means to serve,

What are your ideas here? How does it compare to your vision for ruby-doc?

the visual harmony is a red herring.

Think duck typing. If one class has #to_s, another #to_string and
another #as_a_string, how should the phraser know that those all do
the same thing? The name of a method is to a phraser as a web site's
design is to a visitor.

ruby-lang site says, "Go here to see active Ruby projects", then it's
pretty clear it's related and valuable.

But if the first reaction is "this isn't what I'm looking for", then
the person is going to look somewhere else. The first reaction isn't
based on a "go here", but what they see when they first get there.

But before anyone sets out to update the links on ruby-lang,

Well, what I mentioned has already been done in the time it took you
to write your email

a) this sort of content even belongs there

It doesn't. My first thought was "replace the page with a link to
ruby-doc" then I realised that ruby-doc isn't really at that stage
yet. Better to have the page on ruby-lang for now.

b) if so, how can it be arranged so that keeping up doesn't become a
full-time job?

The easy answer is "make it a wiki"and it's already been done:
http://www.rubygarden.org/ruby/

Why manually update a set of "In the news" links on ruby-lang when you can
just grab and cache RSS feeds?

Why do it at all? There is no need to keep track of every time the
word Ruby is posted on a site. News written by "Ruby", whatever and
whover that is, should really go to one place.

It is not easy to find the right balance, and people ought not be thrust
into "expert mode" right off the bat, but I suspect that many things
that may one thinks of as valuable to a newcomer will quickly strike
them as just more stuff taking up screen space as they soon get more
familiar with a site.

I don't understand what you are trying to say. Are you just being
cynical? That's my impression, sorry if I'm mistaken.

Douglas

 

[Douglas Livingstone]

I also hope others speak up on what the do or don't like; I've asked
this on previous occasions, but typically get very little response, so
it is hard to tell what works and what doesn't.

<rant>

When I look at the ruby-doc index page (http://www.ruby-doc.org/) I
just have an overriding urge to tear apart the design. I want to shove
the mailing list info in a box and get it outof the way. I want to
delete all those dots in the menu, and those square brackets. I want
to remove the massive letter spacing in the ruby-doc title, make it at
least legable.

I just want to plain delete things like "Below are web log entries
with news and announcements concerning documentation efforts." Like
you say, somethings might be useful the first time you see a page, but
after that they just get in the way. "URL-based Documentation
Queries". Cool. Read it once, then use or forget. Give it a link in a
column, get it out of my way.

The news items. Massive areas of white space, do you really need 3em
of space between each line of text?? "Ruby 1.8.2 Final Release"? I
thought this was "complete and accurate documentation" not "latest
Ruby news blog".

"Style"?? At most, four little "A"s like http://wired.com/. A whole
200x300 box is just a wast of scrollbar space.

"Downloads"?? Cool, but that's what the downloads page is for. If
something new gets put in the downloads, post a news item. Otherwise
why bother with both.

"Online Resources", "Articles", "RSS Feeds" - all cool, but what are
they doing in the side bar?? No one will see them 3000px down the
page.

"Third-party API Docs" - cool, but why not just put them with the rest
of the API docs?

"Tools" - again, cool, but they aren't doing any good where they are.
List them on a "how to work with the documentation" page if you must.

"Currently Available Ruby Books" - yep, I saw "Bookstore" complete
with dots and square brackets in the menu... if I wanted books, I
would have used the menu, not scrolled down 10000px first and thought
"ooh, a list f some books!"

And what is news from Sat, 9 Oct 2004 doing on the front page? If it
is useful content, make a section for it. If it isn't, shove it in an
archive so some historian can look at it in a hundred years time and
think how far we've come.

"Colophon" - more of that annoying letter spacing.

Hell, this is all just the front page. I've not even gotten onto what
annoys me about the content of the site itself. Half the problem is
that I haven't already. The thing should be running off site wide
templates, or atleast try and pretend to be on the same URL. It's
worse than the W3C. At least they make things easy to read.

"Blogtari! is written in Ruby, an interpreted object-oriented language."

If I've got this far down the page and I don't know that already,
nothing will save me. And if I cared what language "Blogtari" (silly
name) was written in, I would have clicked the Blogtari! link
already.

And as this seems to be a time for pointing out broken links and
general disrepair, that link at the top of the page to the mailing
list archives? 404 Not Found.

</rant>

 

[Martin DeMello]

I remember the 1980s, not sure about the 1990s. In the 1990s it gots its
ass kicked for one reason. Versus the Atari ST, it was overpriced. Jack
Tramiel got the pricing right and the ST ruled. I'd love to have had an
Amiga. I just could not afford one.

The Acorn Archimedes made the same mistake - I'd have loved an Arc, but
it just wasn't affordable.

martin

 

[James Britt]

I don't understand what you are trying to say. Are you just being
cynical? That's my impression, sorry if I'm mistaken.

Designing for the novice has the potential to create assorted artifacts
that, while useful the first few times someone attempts a task, are
soon no longer needed.

The instructions for joining the ruby-doc mailing list on the main page
of ruby-doc might be a good example. Most people no longer need to be
hit in the face with the mailing list details, but they have to wade
past it each time. It may have been useful for some people for some
period of time, but after 2 or 3 visits, you have to start thinking to
yourself, "Yeah, yeah, I know. This is how I join the list."

So, while the intention may have been good ("Make it easy for people to
learn about the RDP and join in."), the implementation gets in the way
after a while.


James

 

[James Britt]

<rant>

Rant duly noted.

For what it's worth, the site is undergoing a redesign and
reorganization, so your eyes need not suffer much longer. No assurance
at all that it will suit your sense of aesthetics.


James

 

[Douglas Livingstone]

For what it's worth, the site is undergoing a redesign and
reorganization, so your eyes need not suffer much longer. No assurance
at all that it will suit your sense of aesthetics.

It is basic page structure that is missing, things like this:

http://www.webstyleguide.com/page/hierarchy.html

And at a site wide level:

http://www.webstyleguide.com/site/standards.html

Douglas

 

[James Edward Gray II]

<rant>
[snip]

"Third-party API Docs" - cool, but why not just put them with the rest
of the API docs?

While I think many of your points are valid, this one is not.

I feel we should definitely keep a separation of Third-Party APIs and
Core/Standard Library Ruby Docs. Those libraries do not ship with Ruby
and thus the documentation should not be mixed in with libraries that
do, where it could cause a lot of confusion.

James Edward Gray II

 

[Douglas Livingstone]

I feel we should definitely keep a separation of Third-Party APIs and
Core/Standard Library Ruby Docs. Those libraries do not ship with Ruby
and thus the documentation should not be mixed in with libraries that
do, where it could cause a lot of confusion.

It would be sensless to have documentation without making it clear
what is being documented.

Looking at the box again:

Third-party API Docs
Rimport
Tool for importing new data files into ri, using RDoc XML oputput. Now
on RubyForge!

REXML
Pure-Ruby XML parser

The first isn't a link to documentation, infact it is the same link as
the "Rimport" link in the "Tools" section. Either link to the
documentation (I'm not sure that's terribly useful, is the aim or
ruby-doc to collect all documentation about things written in Ruby, or
is it about Ruby itself + documentation on making documentation?) or
don't.

For REXML, isn't that included in the main distribution now? If so, is
it still a 3rd party API?

If those two links dissapear... there isn't a "Third-party API Docs"
section anymore

There may be some merit in having a source for *all* the
documentation, but it would probably be a massive workload to
organise, and if I was looking for documentation I would go and look
for it where I got the thing I'm looking for documentation for, if you
see what I mean

Cheers,
Douglas

BTW: the link to the UK FTP mirror on the ruby-lang downloads page
looks dead: ftp://ftp.mirror.ac.uk/sites/helium.ruby-lang.org/ruby/ on
http://www.ruby-lang.org/en/20020102.html

Same with the HTTP link:
http://www.mirror.ac.uk/sites/helium.ruby-lang.org/ruby/

# United States 3 (binarycode.org) gives an empty "Index of /ruby" directory
# United States 4 (online-mirror.org) is "not found"

Belgium (Easynet) links back to the ruby-lang site, advertising a
download for 1.6.8 and "The first preview of 1.8.0". Probably doesn't
belong in the mirrors list.

The "# United States 1 (lcs.mit.edu)" FTP mirror complains that I'm
on the wrong continent, which is OK I guess.

 

[Tanner Burson]

Designing for the novice has the potential to create assorted artifacts

that, while useful the first few times someone attempts a task, are
soon no longer needed.

The instructions for joining the ruby-doc mailing list on the main page
of ruby-doc might be a good example. Most people no longer need to be
hit in the face with the mailing list details, but they have to wade
past it each time. It may have been useful for some people for some
period of time, but after 2 or 3 visits, you have to start thinking to
yourself, "Yeah, yeah, I know. This is how I join the list."

Well I guess it's my turn to throw down on this subject. I am what
many of you have declared needs to be the new "target market". I've
been working with Ruby for only a couple of weeks now, and I've
gathered a few tidbits of information some of you might find relevant.

The biggest problem I've had is that the closest thing to a site
containing updated links to the things I'm looking for has been
google. All of the "major" websites (ruby-lang.org , ruby-doc.org,
etc) don't appear on the surface to be updated on a regular basis.
After looking into things farther I've found that the sites ARE
updated, but there is no indication of such.

Another large issue I've had is that after some searching there IS a
lot of information out there. The problem being it is across several
dozen sites, written at several dozen different times, using several
dozen different versions of things. There is no source I can find
that accurately aggregates and keeps on top of portions of this
content.

But IMO one of the largest sources of confusion among us newcomers is
that there appears to be a serious duplication of efforts in a lot of
areas. The biggest offenders are RAA and Rubyforge. I still cannot
tell you the difference between a project posted at RAA and one posted
at Rubyforge. Which one should be my primary search when looking for
a library? This problem is something that happens to all languages at
some point, but seems to have hit Ruby fairly early.

Now as for specifics and suggestions
Ruby-Doc.org is a great resource, I use it on a daily basis to look
SOMETHING or other up. The problem is that the multi-frame templates,
while helping simple navigation, kill my attempts to search for
something.

In general, I'd say that the single best resource for ruby, is this
list. I've learned more, and found more great resources from here,
than anywhere.