I never understood why nobody has built a documentation webapp where you just enter the SVN/CVS/GIT of a project and the webapp checks out the code onto the server's backend at a fixed internval then generates documentation from a standardized commenting layout, kind of like doxygen but more social.
It could be neat, you could even have the app merge user submitted comments or changes to documentation (submitted via the web-app) back into the code documentation in the repository. Maybe set a convention where you create a DocApp folder for pages, all synced with the online webapp.
It's been on my To-Do list for ruby-doc.org for, oh, forever.
One issue is in making sure that as the API changes you can still correctly associate past comments to API where still appropriate.
(The auto-svn c/o is in place at least ...)
Not a fan of automatically merging comments back into the source code though. Better to just have someone sensible update the docs when needed and submit a patch.
Often, I wish the rails-core would "bless" one of these documentation sites. Just knowing that DHH has passed his fairy wand over one would bring an amazing amount of traffic, in turn, creating a more robust resource.
And it was good. As I know from personal, recent experience, it is danged hard to learn Rails with my normal surf-around-the-intrawebs method. (I eventually find great content on blogs and message boards, but there's a dearth of good entry-level stuff readily available. *Edit: And good general docs, which this site addresses more directly.)
This looks like a giant step forward for train-kind. Looking forward to using it a lot.
It could be neat, you could even have the app merge user submitted comments or changes to documentation (submitted via the web-app) back into the code documentation in the repository. Maybe set a convention where you create a DocApp folder for pages, all synced with the online webapp.
I hope this is what Nodata is working towards.