| «« Building RadRails with Ant | Testing It Myself »» |
|
About
I'm Ryan Lowe, a Software Engineering graduate living in Ottawa, Canada. I like agile software development and Ruby on Rails.
I write this blog in Canadian English and don't use a spell checker. Typos happen.
Projects
» Full-time Ruby on Rails freelancer
» Full-time with Rails since May 2005 » Former committer for RadRails (now Aptana) » I also have a few Rails side-projects in development: 1. wheretogoinTO.com Toronto nightlife 2. Hey Heads Up! TODO list and sharing 3. Layered Genealogy family history research 4. foos for foosball scoring 5. fanconcert for music fans (on hold) Hiring Rails developers? I can telecommute by the hour from Ottawa, Canada »» Email: rails AT ryanlowe DOT ca
BulletBlog
Now hosted on Hey! Heads Up -- check it out!
Syndication
Pings
Recent
Derek Lowe's (Ryan's older brother) words at Ryan's funeral
blog@ryanlowe.ca no more Forging Email Headers: Good, Bad or Ugly? Sarcastic Dictionary (Part 1 of Many) Tags Hierarchies Twisting Rails is Risky Business Risky Business? My Take on Early Alphas Whoa, it's August 2007 Closing Comments A Postscript to "Growth at the grassroots" »» All Blog Posts
Linkage
del.icio.us/ryanlowe
technorati/ryanlowe.ca/blog Aurora Roy Jim Andrew Trasker Travis Kibbee Karen Dr. Unk Ayana Van Bloggers Joel Spolsky Robert Scoble Tim Bray Dave Winer Raymond Chen James Robertson Ruby/Rails Bloggers rubyonrails.org weblog David Heinemeier Hansson Dave Thomas James Duncan Davidson Mike Clark Jamis Buck Signal vs. Noise Tobias Luetke Amy Hoy: (24)slash7 Jeremy Voorhis Eclipse Bloggers Planet Eclipse EclipseZone Luis de la Rosa Eclipse Foundation Kim Horne Billy Biggs Ian Skerrett Mike Milinkovich Bjorn Freeman-Benson Denis Roy
Archives
  
|
Collaborative Documentation for Eclipse?
Open source software has some great examples of collaborative documentation, where you don't just browse the official docs -- you can also add comments to them to help others. The PHP documentation on PHP.net is a perfect example and they've been doing it for years. Now Ruby and Ruby on Rails are getting into it with rannotate. I've found some excellent code nuggets in these comments. Eclipse has a wiki -- which I think is great -- but could it also benefit from collaborative documentation? Absolutely. The collaborative docs could be based on the official Eclipse platform's existing JavaDoc as a starting point. Eclipse could keep the original online JavaDocs pristine and put the collaborative versions online somewhere else. People could make comments in a class or below each method, or in many other places. Challenges? How to update the collaborative docs when JavaDoc updates are released without affecting the comments on top of them? (ie. fixing spelling mistakes). Question: How many different minor versions of the collaborative docs do they maintain? (ie. 2.1.3, 3.0.x, 3.1.x, 3.2.x and they could even do 3.3.x while it's under development). The comments could be scored so that good tips rise to the top (ie. Slashdot, digg). This could be an interesting Ruby on Rails web project... Posted at June 28, 2006 at 10:47 AM ESTLast updated June 28, 2006 at 10:47 AM EST Comments
The more important question in hand is why noone decided to take my famous article Authoring With Eclipse (http://www.eclipse.org/articles/Article-Authoring-With-Eclipse/AuthoringWithEclipse.html) and make a "Documentation IDE" Let's start with babysteps first :) Then we can focus on collaborative documentation dev, but we need a documentation dev environment first ;) » Posted by: Chris Aniszczyk at June 28, 2006 01:12 PMIt can be web-based, it doesn't have to be done *from* Eclipse. That would be nice later though. :) » Posted by: Ryan at June 28, 2006 01:13 PMI should clarify by saying I meant something fairly informal. The collaborative documentation isn't meant to replace the JavaDoc itself, or books. It's just meant as a place for people to share code and ideas ... a lot like the PHP.net online manual. » Posted by: Ryan at June 28, 2006 01:21 PMI have to say that PHPs docs are great. Having real user examples there helps to show you how to actually use the class/function. That's one of the worst things about Microsoft's docs. They're complete in that they tell you all the functions, and their parameters but most of the time they don't show you examples of how it would be used. Sometimes its even a mystery of how to use the parameters. » Posted by: Kibbee at June 30, 2006 09:04 AM |
