A talk David Green and I gave at EclipseCon 2010 which demonstrates a technique to crowdsourc documentation. While the examples are meant for Eclipse.org, you can easily take the code and apply it to any software project that wants to crowdsource its documentation.

1. Crowdsourcing and Singlesourcing
Documentation at Eclipse
Chris Aniszczyk
caniszczyk@gmail.com
http://twitter.com/caniszczyk
David Green
dgreen99@gmail.com
http://twitter.com/green_david
March 23, 2010 Confidential | Date | Other Information, if necessary
© 2002 IBM Corporation

2. Can you relate? Do you care?
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

3. Why Does Documentation Suck in OSS?
 There’s always more important work to do...
 Most developers don’t like to write documentation...
 Generally a pain to craft...
 The Eclipse Platform help is in HTML...
 DocBook and DITA have learning curves
 In open source communities there are barriers
 Committer Agreements
 Version Control Systems
 So... how do we make it better?
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

4. Crowdsourcing and Accessibility
 Involve more people in the documentation process to make it better
 If it’s hard to contribute documentation, no one will do it
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

5. Making it Easier - The Wiki Way
 So, how do we involve people in the documentation process?
 Use a wiki to lower the barrier to entry!
 Anyone can contribute
 Easy to contribute via wiki markup
 Documentation changes are instantly available!
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

6. Singlesourcing Documentation
 Author once!
 Publish to multiple formats
 web
 Eclipse Help (documentation bundle)
 PDF
 The wiki alone doesn’t help solve this problem...
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

7. Mylyn WikiText
 Provides an extensible framework and set of tools
 Focuses on parsing, editing and presenting wiki markup
 Ant tasks for generating HTML and other formats
 Wiki text editor for Eclipse
 Supports a variety of markup languages
 MediaWiki (this is what Eclipsepedia uses)
 Confluence
 Textile
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

8. Single Sourcing + Crowdsourcing
 People contribute documentation via the wiki
 Ant build downloads wiki content
 Ant tasks generate Eclipse help and other formats...
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

9. Successful Examples from Eclipse.org
 Mylyn
 Uses two wiki pages on Eclipsepedia for its documentation
 http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/
org.eclipse.mylyn.help.ui/build-helper.xml?root=Tools_Project&view=markup
 EGit
 Generates documentation from its user guide on Eclipsepedia
 http://wiki.eclipse.org/EGit/User_Guide
 Xtext
 A slightly different example; uses Textile and Wikitext
 The textile files are in a VCS, making crowdsourcing a bit difficult...
 http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.tmf/org.eclipse.xtext/plugins/
org.eclipse.xtext.doc/?root=Modeling_Project
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

10. Show me the Magic!
http://wiki.eclipse.org/DocumentationGuidelines/Example
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

11. Conclusion
 Single sourcing documentation makes it flexible
 Crowd sourcing documentation lowers contribution barriers
 There is little reason to not use this approach at Eclipse.org
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green

12. Q&A
Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green