Twitter github

Singlesourcing and Crowdsourcing Documentation

One of the most common complaints I hear about open source projects is around documentation, from the complete lack of documentation to just outdated documentation. There’s many reasons why this is the case, from time to skills but I’m not going to go into that. Yesterday at EclipseCon, David Green and I gave a talk about Crowdsourcing and Singlesourcing Documentation at Eclipse and our thoughts on how to solve the documentation problem for Eclipse.org related projects.

While the talk is focused on Eclipse.org related projects, there is nothing in there that prevents you from taking what we did and apply it to your own projects, whether or not they are open source. The key lessons here is that most developers don’t like contributing to documentation to begin with. They also never have the time. On top of that, if the barriers to contributing documentation is high, no one will contribute and you’ll end up with low quality documentation.

Lower those barriers by enabling a variety of people to contribute documentation, not only people with commit access to the project. If you involve and enable the community to contribute, you may be surprised at what contributions you get.

What other experiences have people faced when it comes to open source related documentation? What can make things better?

  • I like the idea of crowd-sourcing very much. Projects like JDocs (http://www.jdocs.com/) tried something similar but weren't that successful I think. On the other hand, Sun's DocWeb project (http://doc.java.sun.com/DocWeb/) seems healthy and documentation is quite often extended by users. I think one major success factor behind such a project is either big name like “SUN”, or “Eclipse” or a very active user community with a large interest on such kind of documentation sourcing. Are there any concrete plans to support crowd-sourcing documentation for Eclipse so far?

    If so, please allow me to call your attention to one of our plug-ins which I think is somehow related to this. We are working on an “extended Javadoc View” to be used as a replacement of the “classic Javadoc View”. Essentially, this view allows for having several documentation providers that provide additional documentation for IJavaElements like classes, methods, fields etc. Initially, we built this view as a proof-of-concept for a research paper. There we investigated whether useful information could be extracted automatically from example code and be used to complete API documentation in a meaningful way. For instance we mined for (what we called) “subclassing directives”, i.e., documentation hints that state which methods should be considered to be overridden, extended or reimplemented by subclasses or which super-calls should be added to a reimplementation of a superclass’ method etc.

    The final documentation of the view is currently under construction so that I can only present the project’s sketchbook page to make the idea more concrete: http://code.google.com/p/code-recommenders/wiki…. However, the current prototype is available at the project homepage and provides such extended documentation for Eclipse JFace and many other Eclipse plug-ins. I think this would fit quite well to the concept of user-provided documentation and I would love to see this in Eclipse. Comments in every direction are welcome 🙂

  • Thanks for the link, I'll definitely give it a try.

    You should try blogging about it on PlanetEclipse if you have a blog.

  • I like the idea of crowd-sourcing very much. Projects like JDocs (http://www.jdocs.com/) tried something similar but weren't that successful I think. On the other hand, Sun's DocWeb project (http://doc.java.sun.com/DocWeb/) seems healthy and documentation is quite often extended by users. I think one major success factor behind such a project is either big name like “SUN”, or “Eclipse” or a very active user community with a large interest on such kind of documentation sourcing. Are there any concrete plans to support crowd-sourcing documentation for Eclipse so far?

    If so, please allow me to call your attention to one of our plug-ins which I think is somehow related to this. We are working on an “extended Javadoc View” to be used as a replacement of the “classic Javadoc View”. Essentially, this view allows for having several documentation providers that provide additional documentation for IJavaElements like classes, methods, fields etc. Initially, we built this view as a proof-of-concept for a research paper. There we investigated whether useful information could be extracted automatically from example code and be used to complete API documentation in a meaningful way. For instance we mined for (what we called) “subclassing directives”, i.e., documentation hints that state which methods should be considered to be overridden, extended or reimplemented by subclasses or which super-calls should be added to a reimplementation of a superclass’ method etc.

    The final documentation of the view is currently under construction so that I can only present the project’s sketchbook page to make the idea more concrete: http://code.google.com/p/code-recommenders/wiki…. However, the current prototype is available at the project homepage and provides such extended documentation for Eclipse JFace and many other Eclipse plug-ins. I think this would fit quite well to the concept of user-provided documentation and I would love to see this in Eclipse. Comments in every direction are welcome 🙂

  • Thanks for the link, I'll definitely give it a try.

    You should try blogging about it on PlanetEclipse if you have a blog.