[ANN] Rubypub.com - A Ruby Documentation Wiki

[Brian Tol]

[ANN] Rubypub.com - A Ruby Documentation Wiki

Rubypub.com is custom-built documentation wiki for Ruby Gems. Features of note:

1. It's loosely based on rdoc's HTML output, although hopefully a bit
nicer to look at.
2. Every README, module/class rdoc and method rdoc is editable. Other
files (docs, mostly) are included, too, though not in edible form.
3. 7,134 total gems are available, with 1,817 being newest releases.
New gems are imported nightly.
4. Every file from every gem is included at files.rubypub.com, and all
the Ruby files are HTMLized [1].

Rubypub's hopes/dreams are twofold:

1. Provide a single-source web site for Gem documentation, making it
easier for Ruby programmers to find documentation. It also offloads a
bit of work from gem authors: they don't need to remember to publish
their rdocs.
2. Allow everyone to easily contribute documentation, and offer that
documentation back to gem authors for incorporation into their
codebases and online docs.

Rubypub is part labor of love, part social experiment. The best case
scenario: it allows the ruby community to produce incredible
documentation extremely fast. Worse case: it makes bad documentation
worse.

There's a few bugs, and probably more than a few warts, but it's
hopefully far enough along to get feedback.

Near-term goals:

1. Nail down the licensing policy. Currently user-contributed
documentation is distributed under a Creative Commons
Attribution-ShareAlike 3.0 Unported Licence, except where doing so
would conflict with the original licensing terms. This seems fair, but
feedback is very much appreciated, as I'm not a licensing guru.
2. Stamp out the bugs and finish a few outstanding features. Please
use the Rubypub Google Group [2] to submit issues and submit ideas.
3. Figure out the best method of delivering contributed docs to
authors. XML? JSON? Patches? Ideas are appreciated.

One final note: Hopefully people find this useful. But if you're a gem
author and would prefer not to include your gems at rubypub, I'm happy
to remove them. Just drop me an email.

[1] Here's a sample:
http://files.rubypub.com/activesupport-1.4.2/lib/active_support.rb
[2] http://groups.google.com/group/rubypub

 

[Phlip]

Props!!

Hopefully people find this useful. But if you're a gem
author and would prefer not to include your gems at rubypub, I'm happy
to remove them. Just drop me an email.

[1] Here's a sample:
http://files.rubypub.com/activesupport-1.4.2/lib/active_support.rb

Why isn't your sample an exemplary README, like this?

http://rubypub.com/gem/sparklines-0.4.5/

And could you submit your style system to RDoc, to save us from those four
dreary frames?

 

[Phlip]

Props!

Brian, since I wrote that 90 seconds ago, I have mailed two links to your
pages out to two co-workers, regarding our projects.

Major props!!

 

[Florian Gross]

3. Figure out the best method of delivering contributed docs to

authors. XML? JSON? Patches? Ideas are appreciated.

Patches sound most useful to me.

And this looks very, very great. Good work!

I could see this becoming an official part of the Ruby homepage.

 

[Trans]

Patches sound most useful to me.

And this looks very, very great. Good work!

I could see this becoming an official part of the Ruby homepage.

Er.. there are all sorts of problems with that.

What if I use slightly different rdoc parameters?
What if I rdoc my app in separate sections?
What if I don't use rdoc?

In those cases this sight presents a very misleading depiction of my
application.

I say leave it to me to document my app, thanks. If you want to create
a tool to help me do that than great, maybe I'll use it, but give me
the choice. I think it's mildly poor taste to do little more than
deliver up other people's docs to make $ with google ads. And I don't
think the wiki feature is useful enough to justify it.

T.

 

[Robert Dober]

One final note: Hopefully people find this useful. But if you're a gem
author and would prefer not to include your gems at rubypub, I'm happy
to remove them. Just drop me an email.

Should it not be the other way around? It surprises me that you
include the doc of gems without any permission of the authors.
It would not make me very happy for sure...

Robert

 

[Gregory Brown]

[ANN] Rubypub.com - A Ruby Documentation Wiki

Rubypub.com is custom-built documentation wiki for Ruby Gems. Features
of note:

This should be very helpful. Thank you for the site.

+1 this looks beautiful

Easy: user-contributed documentation for a gem should be under the same
license as the original gem (either that, or it should be in the public
domain), that way the original author can incorporate good improvements
without needing to worry about licensing conflicts.

In fact, you *need* to do this. You don't have the rights to assume
that documentation from gems are under any license other than what the
author stated for them, and if you choose something like CC by S/A
(which I think is a nice license), you'll need to be sure that every
single project you host is under license terms compatible with it, or
get permission from every author to license the combined works as
such. Sounds like a painful nightmare to me.

So your choices are to either have user contributions be under the
public domain or under the original license scheme. As a package
maintainer, I'd like to throw my vote towards the original license
scheme!

2. Stamp

out the bugs and finish a few outstanding features. Please use the
Rubypub Google Group [2] to submit issues and submit ideas. 3. Figure
out the best method of delivering contributed docs to authors. XML?
JSON? Patches? Ideas are appreciated.

Patches please. The XML and JSON won't be very helpful for quickly
applying the docs to my files.

 

[Rob Sanheim]

Er.. there are all sorts of problems with that.

What if I use slightly different rdoc parameters?
What if I rdoc my app in separate sections?
What if I don't use rdoc?

In those cases this sight presents a very misleading depiction of my
application.

I say leave it to me to document my app, thanks. If you want to create
a tool to help me do that than great, maybe I'll use it, but give me
the choice. I think it's mildly poor taste to do little more than
deliver up other people's docs to make $ with google ads. And I don't
think the wiki feature is useful enough to justify it.

T.

Rdoc and the core doc pages have languished for so long, so its
inevitable that we'll see new tools like rubypub or railsbrain.com
come up. It would be great for folks to also try to improve rdoc
itself, but I welcome something like rubypub if it at least improves
the l&f and usability of plain rdoc.

- Rob

 

[Brian Tol]

Should it not be the other way around? It surprises me that you

include the doc of gems without any permission of the authors.
It would not make me very happy for sure...

To be honest, that was my biggest hesitation in developing the site.
Pissing people off is the _last_ thing I want to do. On the other
hand, since (a) lots of gems need better (or _any_) documentation, and
(b) gems are licensed in such a way that allow for reuse like this, I
thought I'd give it a go.

Ideally I'd like to see a way for authors to opt-out of the system
upfront, so I don't even need to bother with importing and them
removing it.

-
Brian "Chip" Tol
http://www.wiremine.org
(e-mail address removed)

 

[Brian Tol]

Easy: user-contributed documentation for a gem should be under the same

In fact, you *need* to do this. You don't have the rights to assume
that documentation from gems are under any license other than what the
author stated for them, and if you choose something like CC by S/A
(which I think is a nice license), you'll need to be sure that every
single project you host is under license terms compatible with it, or
get permission from every author to license the combined works as
such. Sounds like a painful nightmare to me.

So your choices are to either have user contributions be under the
public domain or under the original license scheme. As a package
maintainer, I'd like to throw my vote towards the original license
scheme!

That sounds great to me. Any other thoughts/suggestions?

2. Stamp

out the bugs and finish a few outstanding features. Please use the
Rubypub Google Group [2] to submit issues and submit ideas. 3. Figure
out the best method of delivering contributed docs to authors. XML?
JSON? Patches? Ideas are appreciated.

Patches please. The XML and JSON won't be very helpful for quickly
applying the docs to my files.

+1. My thinking at this point is to export the docs via JSON, and then
use a tool to utilize this data for patches.

 

[Brian Tol]

Rdoc and the core doc pages have languished for so long, so its

inevitable that we'll see new tools like rubypub or railsbrain.com
come up. It would be great for folks to also try to improve rdoc
itself, but I welcome something like rubypub if it at least improves
the l&f and usability of plain rdoc.

Man, I couldn't agree more. BTW, I don't really see rubypub as a
competitor to rdocs. Like Trans pointed out, not everyone will want to
be included, and, anyways, Rubypub won't work well for all gems.

 

[Gregory Brown]

To be honest, that was my biggest hesitation in developing the site.
Pissing people off is the _last_ thing I want to do. On the other
hand, since (a) lots of gems need better (or _any_) documentation, and
(b) gems are licensed in such a way that allow for reuse like this, I
thought I'd give it a go.

(b) isn't true. What makes you assume that?

*most* gems are licensed this way, but there is no restriction on what
licenses people use by RubyForge as of yet.

 

[Brian Tol]

(b) isn't true. What makes you assume that?

Good to know. I looked through a couple hundred gems looking at
licenses before I started this thing, so that's where I got that idea,
and looked at this page:

http://rubyforge.org/softwaremap/trove_list.php?form_cat=13

The "Other/Proprietary License" licensed projects are either (a) dual
license under GPL, or (b) haven't released anything.

The remaining gems are released under public domain, CC, OSI-approved,
or Ruby licenses. From what I've read, and in talking with other
people, the CC, OSI and Ruby licenses would work with rubypub.

That all said, violating license terms is really antithetical to
rubypub's goals, so more feedback is appreciated. Violating licenses
doesn't help end-users, or gem authors.

 

[Brian Tol]

*most* gems are licensed this way, but there is no restriction on what

licenses people use by RubyForge as of yet.

As a side note:

If nothing else, I hope rubypub can be a discussion starter within the
ruby community about how to best improve and share ruby documentation.
It seems to me that allowing more people to contribute and improve
docs is a good goal to have. As a believer of wikis, I think rubypub
is a good way to start doing this, but it's not the end-all or be-all.

Like I said in the announcement, it's a bit of a social experiment.
Licensing details, data flow and -- most fundamentally -- user
participation, are all unknowns at this point.

 

[Tomas Pospisek's Mailing Lists]

[ANN] Rubypub.com - A Ruby Documentation Wiki

1. The top of the page contains the title and search bar. OK, good. Then
below are "Recently released gems", etc. The indexes are far, far away
at the bottom of the page.

Assumed that the most important things should be at the top and that
the most important thing is the gem's documentation then the indexes
should be at the top and not at the bottom of the page (or they could
also be one in a side bar or such).

2. When I go way down ;-), click on Gems A-Z, then on 'R' and then on
'Next page', then the page I get only contains the *following*
gem in addition to the previous ones and not the following page. Thus
what is happening is problably something like this:

gems_to_display = find(i=i+)

instead of:

gems_to_display = find(i = i + $NUMBER_OF_GEMS_PER_PAGE)

(I have cookies switched off by default)
*t

 

[James Britt]

Should it not be the other way around? It surprises me that you
include the doc of gems without any permission of the authors.
It would not make me very happy for sure...

Has GemJack gotten flack?

http://www.gemjack.com/

It, too, hosts Gem documentation, though without a wiki.


--
James Britt

www.ruby-doc.org - Ruby Help & Documentation
www.risingtidesoftware.com - Wicked Cool Coding
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.jamesbritt.com - Playing with Better Toys

 

[James Britt]

[ANN] Rubypub.com - A Ruby Documentation Wiki

Rubypub.com is custom-built documentation wiki for Ruby Gems.

What's it written in? Ruby?

Is the source code available?

--
James Britt

www.ruby-doc.org - Ruby Help & Documentation
www.risingtidesoftware.com - Wicked Cool Coding
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.jamesbritt.com - Playing with Better Toys

 

[Brian Tol]

What's it written in? Ruby?

Yes! It's basically a rails app with some odds and ends added to
handle the importing process.

Is the source code available?

Not yet. I'd like to clean up and release the rdoc => database engine,
which is a handy little piece of code.

-Brian

 

[Gregory Brown]

Good to know. I looked through a couple hundred gems looking at
licenses before I started this thing, so that's where I got that idea,
and looked at this page:

http://rubyforge.org/softwaremap/trove_list.php?form_cat=13

The "Other/Proprietary License" licensed projects are either (a) dual
license under GPL, or (b) haven't released anything.

The remaining gems are released under public domain, CC, OSI-approved,
or Ruby licenses. From what I've read, and in talking with other
people, the CC, OSI and Ruby licenses would work with rubypub.

There are OSI approved licenses which would not be compatible with CC
S/A, or at least be disputed.

For example, if I use an academic license which restricts certain
things about modification, my code would be open source but not free
software, and that means that third parties may not have the right to
redistribute derived works when it comes to documentation.

These issues are not likely to be numerous, but definitely likely to
be a big mess which you should avoid (and easily can).

 

[Ken Bloom]

Good to know. I looked through a couple hundred gems looking at licenses
before I started this thing, so that's where I got that idea, and looked
at this page:

http://rubyforge.org/softwaremap/trove_list.php?form_cat=13

The "Other/Proprietary License" licensed projects are either (a) dual
license under GPL, or (b) haven't released anything.

The remaining gems are released under public domain, CC, OSI-approved,
or Ruby licenses. From what I've read, and in talking with other people,
the CC, OSI and Ruby licenses would work with rubypub.

That all said, violating license terms is really antithetical to
rubypub's goals, so more feedback is appreciated. Violating licenses
doesn't help end-users, or gem authors.

Just do an automatic check against the gem's listing on Rubyforge, and
make sure it's an open source license. If so, then you're free to put the
docs on your site (assuming you agree with the license yourself), and you
don't have to pay attention to the author's wishes in contradiction with
the license at all. (However, you may choose to do so as a courtesey.)

--Ken