DEV Community

loading...

Help Needed: Where to Put Ruby Docs?

burdettelamar profile image Burdette Lamar ・2 min read

Where, other than in the Ruby project itself, can enhanced Ruby documentation be shared to a broad readership?

(By enhanced, I mean substantially beyond what's in the Ruby doc itself.)

TL;DR

Quite a while back I had the notion to found a GitHub project where I'd write about Ruby. My goals included:

  • Telling examples for everything.
  • Hard-nosed precision (e.g., Hash-convertible objects).
  • Completeness (e.g., all exceptions raised).

Shortly, though, I realized that some of this would represent enhancements to Ruby's own documentation. So, I asked myself, shouldn't it actually be put into the Ruby documentation itself, instead of in a separate (and far less prominent) place? The Ruby doc lives in comments in the Ruby project's code, so that's where the enhancements would go.

Last year I experimented by basically rewriting the documentation for Ruby's ENV object. Happy to say that all that got merged (in small batches) and then released with version 2.7. Here are the before and after versions:

All well and good.

This year I've been working on classes Hash and Array.

I have not, though, been able to get anything (again, in small batches) reviewed and merged. I don't complain about that: Everyone's busy, just like us.

The problem is, I have a huge backlog of documentation now:

  • All 75 methods in Hash.
  • Two-thirds of the 95 methods in Array.

I've stashed all that in my own project, About Ruby. But I don't think that very many in the huge Ruby world will find it there.

So my question is this: Is there someplace else I can put this where people are more likely to find it?

Discussion (7)

pic
Editor guide
Collapse
leastbad profile image
leastbad

This must be so frustrating. I've tweeted a request at @tenderlove aka Aaron Paterson. He's on the Ruby core team and will hopefully know what to do.

Collapse
burdettelamar profile image
Burdette Lamar Author

Thanks, @leastbad . @ioquatix has taken an interest, so things are looking up.

Collapse
burdettelamar profile image
Burdette Lamar Author

Any response from @tenderlove? (A week now and @ioquatix has not merged.)

Collapse
leastbad profile image
leastbad

Unfortunately, not yet - and given that it's been a week, I'm not sure what to expect. To him, I'm just a random on Twitter.

One thing you could try doing is drop a line to Peter Cooper (peter at peterc dot org) and introduce yourself. He's the person behind Ruby Weekly, which is very widely read in the English speaking Ruby world. I have to believe that "My name is Burdette, and I am an #{age} year-old woman sitting on dozens of documentation patches for core Ruby libraries, but I can't get anyone with commit privileges to write me back." is a pretty solid pitch to someone making a good case that they cover Ruby news.

Thread Thread
burdettelamar profile image
Burdette Lamar Author

Thanks, leastbad, for this thoughtful response. I may be starting to get traction via @ioquatix, and possibly others. I appreciate having another bullet to spend if it's needed. (Oh, and, ponytail notwithstanding, I'm a 77-year-old man.) Also, over at the Weekly, I see articles written by Core Team and by Samuel Willians (@ioquatix). Thanks again.

Thread Thread
leastbad profile image
leastbad

Oh gosh, I'm embarrassed. It's a lovely ponytail! :)

Thread Thread
burdettelamar profile image
Burdette Lamar Author

Don't be embarrassed. I get lots of mail addressed Ms.