It’s been overcast and raining here in Victoria B.C. (Canada) over the past 2 weeks. It’s a long way from the dog days of summer, but a good time to focus on docs.  In fact, the Eclipse team has been focusing on documentation during this final release candidate.  In particular, the p2 team is putting some docs together on our new API (Yes, p2 has “real” API now).

Last year Andrew Niefer gave me a few tips on self-hosting the doc / help contents and I thought I would share these.

The help contents are written in HTML files and live in OSGi bundles (like everything else).  For example, the platform doc lives in org.eclipse.platform.doc.isv. Once you have your bundle loaded (from CVS, git, wherever) you can edit the contents like any HTML other document.  When you want to see how the contents will appear to the user, simple launch the org.eclipse.help.base.infocenterApplication, and specify a port as a VM argument (-Dserver_port=4419 for example).

Once running, you can now browse the help contents using your favorite browser (and even change the contents on the fly).

Of course if we get our butts in gear and follow David Green’s advice, we won’t need to edit our docs this way.

Tags: documentation, helios, p2

I’ve been pensive as of late since we shipped the Eclipse Galileo release. One of the things I personally have been thinking about is how we can improve our documentation process. Currently, the Eclipse platform team has its documentation in Eclipse Help format (mostly HTML)… all this is kept in source control. In its current shape, the documentation isn’t conducive for people to contribute. There’s a lot of hoops a potential contributor needs to jump through in order to contribute documentation. Even more hoops if our documentation contributor isn’t really a developer. I also know a few committers who dread doing documentation because they have to hack away at HTML documents.

Can we do better? I think we can.

I’m interested in crowdsourcing the documentation at Eclipse.

What do I mean here? Well, I luckily have one example in the Eclipse ecosystem that is crowdsourcing its documentation already. The Mylyn project has its User Guide on the wiki.

The Mylyn project then uses WikiText to parse this wiki markup via a script and generate relevant Eclipse help artifacts.

In the end, there’s one source for the documentation (the wiki) where a multitude of people can easily contribute to. If we look at the Mylyn User Guide, we can see there was a decent amount of edits involving people who weren’t committers.

I’ve been experimenting with this documentation process for PDE and am pretty happy with it. There were only a couple of roadblocks I hit, but that was mostly around making it easier to use some of the WikiText ant tasks within Eclipse. I also experimented with some html2wiki transformers to help convert some of the existing PDE documentation.

One of the reasons I was inspired to look at crowdsourcing documentation for PDE was an excellent series of articles by Ekkehard Gentz on PDE’s new target platform provisioning story. I thought to myself, how could get Ekke to easily contribute that documentation (or even future docs) to PDE where it could be beneficial to everyone?

One point to bring up is that a lot of the Eclipse documentation is on the Eclipse wiki (Eclipsepedia) already. The Eclipse user community has most likely come across Eclipsepedia already. We can also assume that most people are comfortable with wiki syntax or at least the editor that comes with MediaWiki by default. If this isn’t the case, we can try to install something like the FCKEditor extension for MediaWiki to make it easier.

Another point to bring up is that having the documentation sourced from the wiki may have an interesting benefit due to early adopters. For a real world example, I’ll talk about the Equinox p2 project. There have been some complaints that the p2 documentation wasn’t robust enough for early adopters. Well, what happens if those early adopters would be willing to be part of the documentation process? As users adopt the technology, they can document their experiences along with the p2 committer team. If this was set as an expectation, I don’t think people mind sharing their experiences and being part of a team trying to build a cool technology.

What do people think? Is this good for other Eclipse projects?

Would you be enticed more to contribute to official project documentation if it was easier?

Tags: documentation, eclipse, syndicate, wikitext