On the Eclipse newsgroups, I see lots of questions/answers come through with example code of how to do things. And I often think “gee, that would be a good code example to have in the corresponding Eclipse help topic”. And you wouldn’t need lots of wiki WYSWYG features to pick up those things: a simple swipe-copy-paste into the corresponding help topic wiki page would be a step up from what’s possible today.

As David Carver noted, wiki syntax does have some shortcomings. In particular some MediaWiki syntax makes it easy to produce malformed HTML, which web browsers handle just fine but the Eclipse help system doesn’t — it expects well-formed XHTML. Also community contributions likely won’t have planned out organizational structure. It will still take project-level resourcing to ensure high quality documentation.

To address these issues in the Mylyn project we do these things:

* Documentation is sourced from the wiki, but rather than have it sourced with every build automatically, it’s a manual process. This allows for a team member to update the bundled documentation while carefully reviewing changes.
* Generated Eclipse help documentation (HTML) is kept in CVS and formatted, facilitating the review process with Eclipses’ excellent diff tooling.
* The import-from-wiki process involves validation to ensure well-formed XML content, so that errors in the document format can be corrected at build time rather than discovered by end users.
* Bundled documentation has a section added describing how to contribute (ie: location of the page on the wiki).

http://bugs.eclipse.org/214139

The goal is to take advantage of Eclipsepedia which is running on MediaWiki now.

If we set expectations within the Eclipse community that documentation is sourced from certain places within Eclipsepedia… I think we would see more contributions. I can state many examples… from Ekke writing a mini-book on the new PDE target platform provisioning story… to Robert blogging about patch fragments…

Oh, in regards to IP issues… there are none with the wiki because you agree to the Terms of Use when you contribute to the wiki (look at the bottom of the wiki for the notice).

I think this is a fantastic idea. Anything we do to make the documentation process easier would encourage much more quality documentation. I think the internal productivity is just as important as involving others. I’m one of those who dread doing documentation; not because writing the text or taking the screenshots is difficult, but because I have to do so much html editing and site configuration. And since I don’t care for any of the html editors, I end up doing it in plain text by hand. Peter, I think you may be under-estimating the likelihood of outside involvement if barriers were removed. I think users really enjoy sharing what they know, and you can see this in the number of blog posts that are out there about various intricacies of tool use. Some of the best install guidelines for many pieces of software are put together by some frustrated user out there.

But this begs a question that is always relevant WRT Eclipse. What about IP issues? Do they create a barrier, and OTOH, is it always OK to include Wiki contributions with automatically generated project Help bundles? Do people just have to have a bugzilla account and related agreement in order to contribute to project Wiki, and is that enough?

-Miles

dreaming: in eclipse wiki the possibility to insert documentation from a specific blog entry – per ex. an interface to the RSS and choose an entry to import.

perhaps – as bryan says – Google Wave could be a solution to do those things in the future

ekke

XML suffers from the same issue, but DocBook is widely used through out the Open Source world as a common interface. There are Free WYSIWYG editors for XML files like XMLMind (free for open source use). There is also the hosted VEX editor which gives you Visual Editing via CSS stylesheets.

I think we are on the right track, we just need to get it to the point where users aren’t confronted with Markup and get it so they can edit the way they have become accustomed to from Word and other editors. The lower the barrier to entry the better off we will all the projects will be. Documentation for many eclipse projects is in a sorry state.