What's Next?

#ruby #documentation

For the last 18 months or so I've been contributing to the Ruby documentation. Now I'm looking for good opportunities to contribute further.

Please suggest possibilities for your favorite class or module. These might include:

Introductory material.
Methods documentation.
Recipes or tasks.
Tutorial.

Already done:

ENV: Rewrote introduction and methods documentation; old, new.
Hash: Rewrote introduction and methods documentation; old, new.
Array:
- Rewrote introduction and methods documentation; old, new.
- Added section "What's Here": new.
String:
- Rewrote documentation for many methods: old, new.
- Added section "What's Here": new.
doc: Added page "Dig Methods" and linked to it from the relevant classes: new.
Enumerable: Added section "What's Here": new.
CSV:
- CSV: Rewrote introduction and methods documentation: old, new.
- CSV::Table: Rewrote introduction and methods documentation: old, new.
- CSV::Row: Rewrote introduction and methods documentation: old, new.
- Added recipes for parsing, generating, filtering: new.
REXML:
- REXML::Element:
- Rewrote introduction and methods documentation: old, new.
- Added section "What's Here": new.
- REXML::Elements: Rewrote methods documentation: old, new.
- REXML::Elements: Rewrote methods documentation: old, new.
- Added tasks pages: new.
JSON: Rewrote introduction and major methods documentation: old, new.
OptionParser (merged, but html not yet visible on the web):
- Added document option_params.rdoc.
- Added document tutorial.rdoc.
Set (not yet merged): "What's Here" section.

Top comments (10)

Dave Horan • Sep 19 '22

I just came across this as I'm now managing 2 (and soon 3) RoR teams. Thanks so much for your contributions to the documentation! This is the much needed and often underlooked piece of a successful open source project.

Tobias • Apr 23 '21

Wow. Sounds really awesome! Thanks for your engagement in the community. :)

Why do you like writing docs, etc. so much? I'm always pretty lazy when it comes to good docs. What's your secret? 😄 Do you contribute to code too or do you only want to contribute to docs?

We have published an access control gem which is lacking good docs and a wiki. It's still pretty unpopular, however if your are interested in contributing, let me know. 😊

Burdette Lamar • Apr 23 '21

Thanks, Tobias.

I'm building a technical legacy.

I'm especially interested in a few classes that should be far more accessible, the therefore possibly far more widely used. I'm thinking of CSV and REXML.

Tobias • Apr 23 '21

That sounds interesting. Are you only interested in the Ruby docs or are you also interested in other open source projects (within the Ruby ecosystem)? I think there are so many low hanging fruits in the Rails ecosystem alone.

You are able to improve docs that are already at least average quality. There are so many popular and far reaching projects, that are probably not going anywhere soon, that have a long way to good documentation.

Burdette Lamar • Apr 23 '21

Any specific suggestions? As for Rails, I know nothing about it -- would be a steep learning curve for an old dog.

Tobias • Apr 23 '21

Rails itself even has a section for docs in its contribution guide. You can contribute to the Rails Guides or to the Rails API if you want to get into code. Rails has currently 46 open issues open labelled with docs. So plenty of stuff to get into.

On your point with the steep learning curve: Yes, Rails has a steep learning curve if you want to master the framework and build applications with it. But you should not have any problems if you want to contribute to parts of the docs. Maybe knowing meta programming would be an advantage if you want to dig into the code. Rails is pretty heavy on this.

However if Rails itself is too overwhelming, you can also start with other gems. Here are a few examples:

github.com/TFM-Agency/active_entry - This is our gem that I've talked about :)
github.com/diaspora/diaspora/label...
github.com/rubocop/rubocop/labels/...
github.com/sinatra/sinatra/labels/... - A Rails alternative
github.com/spree/spree/labels/Docu... - An Ecommerce solution built on Rails
github.com/postalhq/postal/labels/...
github.com/Shopify/liquid/labels/D...

As you can see plenty of stuff to do in terms of docs here.
I think somebody with your qualifications would be a great win for the community and the docs.