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 : http://github.com/lifo/doc-rails/tree
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 ;-)
And it doesn’t even take up much of your time! All you have to do is stumble across a method or class that isn’t documentated and document it! I haven’t been going that way, I’ve opted for the trudging through file-by-file through what I know and editing it up.
I think everyone’s making some awesome progress. Pretty soon Rails should be over-documentated. Nobody will ask any questions! That’ll be the day.
I had this idea for combining api.rubyonrails.org + Git that would allow people who are logged in to click on a section and edit the docs in-line. This would update the docs in the source directly and save it to git. You’d still have to verify everything as before, but the barrier to entry would be even lower, and people could fix the docs while using them.
Great idea Dan, I think this could be worth digging into and could be generalized to a lot of other projects.
Projects should eagerly seek to lower the barrier to entry for both documentation and code. “Git-era of social development”, here we come.
I approve of this project.
Pratik,
Does this mean Rails is now moving towards / being developed using plain Git (no more git-svn)? It would be amazing.
Michael, Rails will be moving all the development to Git very soon! Stay tuned :)
Pratik,
Finally Rails is moving to distributed VCS. That’s a fantastic thing to hear!
@Dan Kubb: I like that idea as well, and recently posted it here: http://groups.google.com/group/rubymendicant/browse_thread/thread/9e6e85adbf16b400
Count myself among those who would like to contribute, but just needs to get up-to-speed with Git. (yes, I have the Peepcode screencast)
- nathan