Revision as of 17:08, 10 March 2010

Introduction

There are many ways to generate help content in Eclipse. One particular method involves generating your help content from the wiki which allows you to crowdsource your documentation. By having your documentation on the wiki, you lower the barrier of entry for people to contribute documentation. The purpose of this wiki entry is to guide you through an example of how you can crowdsource your documentation using Mylyn WikiText.

What is WikiText

Mylyn WikiText provides an extensible framework and tools for parsing, editing and presenting lightweight markup. On top of that, it has a wiki text editor for Eclipse and Ant tasks for converting lightweight markup to HTML and other formats. In this specific example, we will be using WikiText's ability to convert Mediawiki content into Eclipse help content.

A Simple Example

The best way to learn is by doing. As an example, we will take this wiki entry and create some Eclipse help content from it. To accomplish this, we will use Ant so you can easily integrate this into a build if you wish.

Setting up the Classpath

The first order of business is to setup your Ant classpath so you can use the WikiText Ant tasks.

You can download the WikiText SDK which contains the jars you'll need. In our case, we only need the org.eclipse.mylyn.wikitext.core_1.3.0.I20100116-0000-e3x.jar and org.eclipse.mylyn.wikitext.mediawiki.core_1.3.0.I20100116-0000-e3x.jar since we are only working with Mediawiki. If we were working with something like confluence, we would have to grab the respective JAR and put it on our classpath.

In the end, your Ant file will look something like the snippet below.

<path id="wikitext.tasks.classpath">
	<fileset dir="lib">
		<include name="org.eclipse.mylyn.wikitext.*core*.jar"/>
	</fileset>
</path>

<taskdef classpathref="wikitext.tasks.classpath" 
 resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties"/>
<taskdef classpathref="wikitext.tasks.classpath" 
 resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties"/>

Converting to Eclipse Help

After we have setup the classpath for our task, we need to go and fetch the wiki content and convert it to Eclipse help. This is accomplished via the mediawiki-to-eclipse-help Ant task.

In the end, your Ant file will look something like the snippet below.

<mediawiki-to-eclipse-help
    	wikiBaseUrl="http://wiki.eclipse.org"
		validate="true"
		failonvalidationerror="true"
		prependImagePrefix="images"
		formatoutput="true"
		defaultAbsoluteLinkTarget="doc_external"
    	dest="${basedir}"
    	title="Crowdsourcing Documentation"
    	generateUnifiedToc="false">
    	<path name="DocumentationGuidelines/Example" 
                title="Crowdsourcing Documentation" 
                generateToc="true"/>
    	...

When the Ant task is executed... TODO

Source Code

The full source code for this example is available on GitHub.

Other Approaches

TODO... talk about things as using just textile files (like Xtext does)

Tips and Tricks

You can use <pageAppendum> to add some extra information to your documentation. It's common to add a blurb about how to update the documentation so users can be informed that the documentation they are reading has been generating from the wiki.

Eclipse.org Reference Projects

If you're looking for other examples on how to crowdsource your documentation at Eclipse, the best place is to look and see what other Eclipse.org projects are doing.

Mylyn

The Mylyn project uses a single wiki page on Eclipsepedia for its documentation.

You can browse the source code here. Pay attention to the build-helper.xml

EGit

The EGit project uses a single wiki page on Eclipsepedia for its documentation.

Xtext

The Xtext project uses a Textile and Wikitext for its documentation. This is different from what we desc