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:
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?
Top comments (7)
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.
Thanks, @leastbad . @ioquatix has taken an interest, so things are looking up.
Any response from @tenderlove? (A week now and @ioquatix has not merged.)
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.
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.
Oh gosh, I'm embarrassed. It's a lovely ponytail! :)
Don't be embarrassed. I get lots of mail addressed Ms.