Improve Rails Documentation
Published about 7 years ago

This is almost a cross post from my email to rails-core mailing list :

Lately there had been many tiny doc patches at trac, which could easily escape our normal verification cycle. On top of that, we’re entering the whole new git-era of social development which eliminates the notion of “core” in a way.

Our aim is to make it really easy to get your doc patches in main repository. So to move forward, I’ve setup a git repository at GitHub :

I plan to give commit access to everyone who in the past have written a decent doc patch. Or anyone who is interested in writing one ( and can prove the quality of it by submitting at least one patch via whatever method ). And I’ll be syncing it with main Rails repository every week or so, after verifying all the changes.

So if you’re interested, you could email me directly or even easier is to catch me on IRC ( nick : lifo ). And once I add you to the doc-rails github project, you can commit directly to the repository without forking it ( and not bother about chasing anyone to pull your changes ).

Due to nature of this project/experiment, we’re gonna have to follow a strict set of guidelines for committers :

  • You are only allowed to change only docs and absolutely nothing else.
  • You should spell check your changes.
  • You shouldn’t add an entry to CHANGELOG. ( I will be adding changelog entries when syncing with main repo )
  • If you’re introducing a whole new style of doc writing, you should verify it with me first before you commit it.

Violation of any rule will result in lose of commit rights.

This is just a start. Moving forward, we could even do hackfest for writing docs and probably try to convince caboose doc fund holders to support this move in any way possible. But it all really depends on how things work out with doc-rails.

So anyone who has ever complained about quality of Rails API docs, now is your chance.

The project received a very positive response on the first day. We got whopping 8 patches !!

Now that you’re at it, you should follow Evan Weaver’s advise and throw some love all around ;-)