As David Green mentioned recently, there’s been some momentum building around documentation best-practices at Eclipse. Documentation has always been one of those pain points in Eclipse (or for most open source projects imho), from lack of consistency to not being able to leverage your community to improve the situation.
Through the work of the Eclipse Architecture Council (in particular, Dave Carver) we now have a set of basic documentation guidelines at Eclipse that projects can reference. There’s actually some good stuff in there with pointers to other open source projects on how they handle documentation (e.g., Ubuntu). However, there was one missing piece from those guidelines that always bothered me. For most Eclipse.org projects, the barriers are too high to contribute to the documentation because you generally need access to the source control system and commit access (on top of learning what format the documentation is).
For awhile, a few of us had the thought of leveraging the Eclipsepedia wiki as a source and generate documentation from that. If you use the wiki, all people need is a Bugzilla account and learn simple wiki markup in order to contribute documentation; people don’t need to be committers to contribute documentation! The Mylyn project pioneered this approach with their user guide and FAQ through the usage of WikiText. The only problem with the WikiText approach at the time was that there wasn’t an easy consumable example for people to use and learn from. Thankfully, this won’t be a problem anymore.
At EclipseCon 2010, David Green and I will be giving a talk on Documentation: Single-Sourcing, Crowd-Sourcing And Other Voodoo. As part of preparing for the talk, we created a nice example people can use when exploring WikiText. The example takes the wiki page of the example itself and generates some Eclipse help content from it. You can grab the actual code for the example from GitHub.
We hope the example serves people well and that more Eclipse.org projects start looking to source their documentation from the wiki. If you have any questions, feel free to let us know.
Otherwise, please join us for our talk at EclipseCon if you can.