RDoc with external resources
I have been thinking about ways to improve Rails documentation and have an idea that I would like feedback on.
First off let me say that I’m a big fan of directing time and effort to making the rdocs great because it is “straight from the source” and changes along with the evolution of Rails.
Still, some portions of Rails require more explanation. Take associations for example. I believe the rdocs should show simple examples demonstrating proper syntax. But to really learn about associations you’d want to know about extending associations through blocks. Or maybe how to use with_options to simplify multiple has_many calls with similar options. This knowledge is currently available from the many excellent Rails blogs.
So the idea is to create links to blog posts (or other external resources) from the rdoc based on relevancy to a particular class or method.
Here is how it would work:
1) A simple public app would expose a form to add a “resource”. A resource would likely be a blog post but could also be a great post from the mailing list explaining a certain class or method.
The form could be super simple like:
Resource url (text field): ____________________________ Rails Class (drop down): ____________________________ Class method (drop down): populated from drop down above
2) A maintainer would then approve the resource and ensure the categorization was accurate.
3) Rdocs would be run and the resulting html adjusted to add links to the external resources.
I imagine the links to be non-intrusive, much like the Django Book. This way the rdocs are not disrupted but a user can dive into the extra resources if he or she choses.
Eventually I can see a Mephisto plugin to make submittal automatic when an author publishes a new post. I can also see tagging certain classes and methods of Rails. This would solve the Rails Cross Reference problem as well. For example, if a user wants to learn about web services and searches for REST, they can discover map.resources(…).
I’d be more that happy to build the system if there is interest from the community.