• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Crowdsourcing and Singlesourcing Documentation
 

Crowdsourcing and Singlesourcing Documentation

on

  • 4,176 views

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 ...

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.

Statistics

Views

Total Views
4,176
Views on SlideShare
4,172
Embed Views
4

Actions

Likes
3
Downloads
26
Comments
1

2 Embeds 4

http://www.slideshare.net 2
http://www.scoop.it 2

Accessibility

Categories

Upload Details

Uploaded via as Apple Keynote

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel

11 of 1 previous next

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />
  • <br />

Crowdsourcing and Singlesourcing Documentation Crowdsourcing and Singlesourcing Documentation Presentation Transcript

  • 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
  • Can you relate? Do you care? Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green
  • 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
  • Show me the Magic! http://wiki.eclipse.org/DocumentationGuidelines/Example 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
  • Q&A Eclipse Foundation, Inc.Crowdsourcing Documentation at Eclipse | © 2010 by Chris Aniszczyk and David Green