Crowdsourcing and Singlesourcing Documentation

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

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

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

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

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

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

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

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

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

Crowdsourcing and Singlesourcing Documentation

by Chris Aniszczyk on Mar 21, 2010

Accessibility

Categories

Tags

Upload Details

Usage Rights

1 Embed 2

Statistics

Crowdsourcing and Singlesourcing Documentation — Presentation Transcript