Crowdsourcing and Singlesourcing Documentation
Download as KEY, PDF3 likes3,743 views
The document discusses challenges in documentation for open source software and proposes crowdsourcing as a solution to improve contribution. It advocates using wikis to lower entry barriers and highlights the integration of single sourcing and crowdsourcing to facilitate diverse documentation formats. Successful examples from eclipse.org demonstrate the effectiveness of this approach in enhancing documentation quality.
Crowdsourcing and Singlesourcing 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