Forum: Ruby Rubypub.com - A Ruby Documentation Wiki

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
F361c70e8d51674fa7dc3aa69e04e739?d=identicon&s=25 Brian Tol (Guest)
on 2007-07-27 03:36
(Received via mailing list)
[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/a...
[2] http://groups.google.com/group/rubypub
851acbab08553d1f7aa3eecad17f6aa9?d=identicon&s=25 Ken Bloom (Guest)
on 2007-07-27 16:11
(Received via mailing list)
On Fri, 27 Jul 2007 10:35:56 +0900, Brian Tol wrote:

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

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

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.

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.

http://rubypub.com/gem/SqlStatement-1.0.2/SQLState... has
issues with leading # signs showing up in documentation where they're
not
supposed to, and where they didn't show up in rdoc-generated HTML.

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

On the whole, a very nice site.

--Ken
E0ed615bd6632dd23165e045e3c1df09?d=identicon&s=25 Florian Gross (Guest)
on 2007-07-27 16:52
(Received via mailing list)
> 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.
45196398e9685000d195ec626d477f0e?d=identicon&s=25 Trans (Guest)
on 2007-07-27 17:09
(Received via mailing list)
On Jul 27, 7:50 am, Florian Gross <flor...@gmail.com> wrote:
> > 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.

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.
703fbc991fd63e0e1db54dca9ea31b53?d=identicon&s=25 Robert Dober (Guest)
on 2007-07-27 17:24
(Received via mailing list)
On 7/27/07, Brian Tol <wiremine@gmail.com> wrote:
<snip>
>
> 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
31e038e4e9330f6c75ccfd1fca8010ee?d=identicon&s=25 Gregory Brown (Guest)
on 2007-07-27 17:25
(Received via mailing list)
On 7/27/07, Ken Bloom <kbloom@gmail.com> wrote:
> On Fri, 27 Jul 2007 10:35:56 +0900, Brian Tol wrote:
>
> > [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.
Df5e7adb20adae6c120b04e7cafb15a0?d=identicon&s=25 Rob Sanheim (rsanheim)
on 2007-07-27 17:28
(Received via mailing list)
On 7/27/07, Trans <transfire@gmail.com> wrote:
> > I could see this becoming an official part of the Ruby homepage.
> 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
F361c70e8d51674fa7dc3aa69e04e739?d=identicon&s=25 Brian Tol (Guest)
on 2007-07-27 17:32
(Received via mailing list)
> 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
wiremine@gmail.com
F361c70e8d51674fa7dc3aa69e04e739?d=identicon&s=25 Brian Tol (Guest)
on 2007-07-27 17:34
(Received via mailing list)
> 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.
F361c70e8d51674fa7dc3aa69e04e739?d=identicon&s=25 Brian Tol (Guest)
on 2007-07-27 17:38
(Received via mailing list)
> 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.
31e038e4e9330f6c75ccfd1fca8010ee?d=identicon&s=25 Gregory Brown (Guest)
on 2007-07-27 17:44
(Received via mailing list)
On 7/27/07, Brian Tol <wiremine@gmail.com> wrote:

> 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.
F361c70e8d51674fa7dc3aa69e04e739?d=identicon&s=25 Brian Tol (Guest)
on 2007-07-27 18:11
(Received via mailing list)
On 7/27/07, Gregory Brown <gregory.t.brown@gmail.com> wrote:
> On 7/27/07, Brian Tol <wiremine@gmail.com> wrote:
>
> > 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?

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.
F361c70e8d51674fa7dc3aa69e04e739?d=identicon&s=25 Brian Tol (Guest)
on 2007-07-27 18:21
(Received via mailing list)
> *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.
38ed06ce1dd79b986574e9c7b7b374f8?d=identicon&s=25 Tomas Pospisek's Mailing Lists (Guest)
on 2007-07-27 18:39
(Received via mailing list)
On Fri, 27 Jul 2007, Brian Tol wrote:

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

--
Ff9e18f0699bf079f1fc91c8d4506438?d=identicon&s=25 James Britt (Guest)
on 2007-07-27 19:06
(Received via mailing list)
Robert Dober wrote:
> On 7/27/07, Brian Tol <wiremine@gmail.com> wrote:
> <snip>
>> 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...

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
Ff9e18f0699bf079f1fc91c8d4506438?d=identicon&s=25 James Britt (Guest)
on 2007-07-27 19:18
(Received via mailing list)
Brian Tol wrote:
> [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
F361c70e8d51674fa7dc3aa69e04e739?d=identicon&s=25 Brian Tol (Guest)
on 2007-07-27 19:45
(Received via mailing list)
> 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
31e038e4e9330f6c75ccfd1fca8010ee?d=identicon&s=25 Gregory Brown (Guest)
on 2007-07-27 20:45
(Received via mailing list)
On 7/27/07, Brian Tol <wiremine@gmail.com> wrote:
>
> 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).
Aafa8848c4b764f080b1b31a51eab73d?d=identicon&s=25 Phlip (Guest)
on 2007-07-27 21:27
(Received via mailing list)
Props!!

Brian Tol wrote:

> 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/a...

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?
Aafa8848c4b764f080b1b31a51eab73d?d=identicon&s=25 Phlip (Guest)
on 2007-07-27 21:30
(Received via mailing list)
Phlip wrote:

> 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!!
851acbab08553d1f7aa3eecad17f6aa9?d=identicon&s=25 Ken Bloom (Guest)
on 2007-07-27 21:43
(Received via mailing list)
On Sat, 28 Jul 2007 01:10:16 +0900, Brian Tol wrote:

>
> 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
31e038e4e9330f6c75ccfd1fca8010ee?d=identicon&s=25 Gregory Brown (Guest)
on 2007-07-27 22:54
(Received via mailing list)
On 7/27/07, Ken Bloom <kbloom@gmail.com> wrote:
> >>
> >
> 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.)

Open source does not (necessarily) mean freely modifiable.  Please be
sure that if you do this, that the licenses you check for are
compatible with CC S/A, not all will be.
This topic is locked and can not be replied to.