Momentum is building around documentation best-practices at Eclipse. EGit, Eclipse's Git integration project, recently became the latest project to adopt a crowdsourcing approach to documentation, and is reaping the benefits: in one day they've already seen the contribution of Git for Eclipse Users from Alex Blewitt.
They are able to do this by taking advantage a new feature of the latest Mylyn WikiText, which can generate Eclipse help directly from a wiki. While it was possible to process individual pages before, now Mylyn WikiText makes it easy to process multiple wiki pages at once while automatically downloading images, maintaining page cross-references, and building a unified table of contents.
You can learn more about crowdsourcing documentation at EclipseCon 2010, where Chris Aniszczyk and I are co-presenting Documentation: Single-Sourcing, Crowd-Sourcing And Other Voodoo. If you can't wait two weeks, you can find out how they're doing it at EGit from their contributor guide.
Updated 4/21/2010: Thanks to Chris, a working example with documentation and source is available at DocumentationGuidelines/CrowdSourcingExample
5 comments:
Hallo David,
This sounds very cool! Are there any examples of the Ant tasks for building Eclipse help files from Confluence wiki, or perhaps any documentation about doing it, using the latest version of WikiText? I've seen Chris Aniszczyk's blog post and used his example to generate the help files from Mediawiki. Awesome, it works like a charm. I've downloaded the WikiText SDK and extracted the WikiText core and Confluence JARs. Now I'm wondering if anyone has put together the Ant files for Confluence. (Speaking as an Ant noob!) I'd like to try generating Eclipse help from my localhost version of Confluence 3.2. Any pointers very welcome.
Cheers
Sarah
@ffeathers Mylyn WikiText can generate Eclipse Help from Confluence markup, however the markup must exist on the local filesystem. Contributions are welcome in this area, it would be great to have Ant tasks that download markup and images from Confluence as we currently have for MediaWiki.
The PsychoPath Processor and XSL Tools also use the Eclipse Wiki, Mylyn WikiText, and The Docbook Projects stylesheets.
I've updated the guideline page as well with this information.
Hi David,
At a new work here, the documentation is messy organized. The documentation is here, down in a number of different word-files from different contributors - all with their own revision history.
My plan is to use a mediawiki-engine, which I have set up on a Linux-machine, with a number of extension ( like the Collection:Extension with the 'create a book' option ).
Right now I am able to pick up some facts ( for instance the page 'Projects' ) and then some other facts ( ~ page 'Servers' ) and create a nice PDF - which is sufficient if a were to go to a meeting with the support staff.
At this moment I am thinking about structure and categories, setting up a static navigation panel on the right and thinking about some kind of template that my co-workers have to abide by ( for instance: Every project have to have the following documents ( 1 ) introduction ( 2 ) revision ( 3 ) design specifikation ... ).
Would that be possible, create some kind of DTD that holds my structure for a category ?
Being able to convince my boss that this is a good idea I have to have a decent editor ( might be the wikitext within Eclipse ) so that even he can use it to write documents.
Is the last paragraph here just a dream, are there no good editors to be found so that I can lure by colleges into the beautiful world of wiki ?
if my questions are too deep maybe you could point be to some literature in the area ( I am a Java system developer, not coming from this world )
best regards, Inki
@Inki great to hear about your efforts to improve the state of documentation for your team. Generally wikis are designed to be permissive wrt content, rather than restrictive. I'm not aware of any technologies that you can use to enforce the structure of documents on your wiki. There have been some efforts to combine DITA with wiki, though I'm not sure how far that technology has come.
A recent improvement to Mylyn WikiText is templates, which allows you to provide document templates with predefined structure. While templates won't require your team to conform to a specific format, it may encourage them to do so by providing a standard format for your documents.
Post a Comment