DocBox: Wiki-Like Ruby / Rails Documentation For Everyone
DocBox is the latest attempt to improve the Ruby/Rails documentation scene. Created as a Google Summer of Code project by Ian Ownbey (mentored by Jeremy McAnally) DocBox "sits on top of RDoc and allows users to update documentation through a wiki-like interface." Changes to the 'wiki' are then folded back into your code and committed to a git documentation branch.
While still young, this project shows a lot of promise, as it allows anyone to write detailed, versioned, documentation without having to download or view any source code.
Naturally, DocBox is open source and is available at GitHub. Jeremy and Ian both encourage people to jump in.
July 31, 2008 at 3:27 pm
The Welcome Message does not inspire confidence. The author sounds like a kid who lacks the discipline and could easily lose interest.
August 1, 2008 at 3:35 pm
Hm, what makes you say that? I think it is okay for a project in its infancy.
What don't you like, and what would you suggest instead?
August 1, 2008 at 4:39 pm
This is great to hear. Going from finding a problem with the docs to fixing the problem has never been a cake walk. That discourages many simple fixes which could really improve the API docs as a whole. Providing a wiki interface should help a lot in this area.
Now the final frontier is to integrate this with where you actually read the docs (api.rubyonrails.org and others). Then fixing a simple typo will just take seconds instead of minutes.
August 1, 2008 at 5:05 pm
I like the model recently adopted by some projects for code: If you're first patch is good then you're given commit rights. Since all changes become git commits, anyone with commit rights should be able to implement the changes immediately (which are then reflected in the doc wiki.)
That weeds out the spam/bad posts but allows most people to consistently update the documentation.
August 15, 2008 at 4:16 pm
Also, the fact that it's been in a hacked state since I first looked last night is not a good sign...