Uploaded on

 

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
366
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
0
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1.
      • Recent Research on Community Participation in Software Documentation
      • Andy Oram — Editor, O'Reilly Media
      • July 25, 2007
  • 2. Overview of talk
      • How effective is user-contributed documentation? (Research on mailing lists)
      • Why do people contribute? (Survey results)
      • How do we measure effectiveness? (Quiz demo)
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 3.
      • Research on mailing lists
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 4. Questions answered on mailing lists
      • Only half of technical questions on popular Linux-related lists are resolved successfully.
      • Over one-fourth receive no response at all.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007 Number of responses to unresolved questions.
  • 5. Noise on mailing lists
      • Postings on a thread that do not contribute to an answer take up time and energy.
      • This chart counts only the postings that reply directly to a technical question.
    Questions: helpful, irrelevant, initial, and unhelpful Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 6.
      • Survey on contributions to free documentation
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 7. Reasons to contribute
      • Community Personal Growth
      • Mutual Aid Gratitude
      • Informal support Reputation building
      • The enjoyment of writing Thrills
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 8. Reasons to contribute (definitions)
      • 1. Community
      • People who care about a software project want to build a community around this. They contribute to draw other people into the community, and perhaps to set standards for use of the software as well as standards for participation in the community.
      • 2. Personal Growth
      • By offering advice to others and by following them through the process of repairing a problem, contributors build their own diagnostic and communication skills.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 9. Reasons to contribute (definitions)
      • 3. Mutual Aid
      • People contribute help in the expectation that they'll get help in turn when they need it.
      • 4. Gratitude
      • People say, "I received help when I was new to this technology, so I want to help others."
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 10. Reasons to contribute (definitions)
      • 5. Informal support
      • Many software developers and other people go on forums to offer technical support, which promotes use of the software.
      • 6. The enjoyment of writing
      • Many people like to write, and may decide their skills will be put to good use on this software project.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 11. Reasons to contribute (definitions)
      • 7. Reputation building
      • Consultants, trainers, job-seekers, authors, and others who hope to build a career go online to build up recognition and respect.
      • 8. Thrills
      • There's pleasure in seeing your insights turn up almost instantly on a forum with worldwide scope, as well as watching others succeed with your help and praise you for it.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 12. Number of ratings for each reason Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 13. Analysis of ratings for reason Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
      • Community was the top reason, followed by Personal Growth.
      • Reputation came in only 6 th or 7 th , but was still 75% as popular as the top-rated reason, Community.
  • 14. Reasons ranked by importance Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 15. Analysis of ranking by importance Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
      • The Community reason not only came out on top, but was the only reason that received more ratings as "Extremely important" than as "Important." Two related reasons, Mutual Aid and Gratitude, also ranked high.
  • 16. Free versus proprietary software Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007 Note: only a handful of respondents fell into the proprietary category.
  • 17. Analysis of free versus proprietary Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
      • Because the proprietary line is based on only 9 respondents, no conclusions can be drawn.
      • Still, it's intriguing that free software respondents reported much higher ratings for Community and Mutual Aid.
  • 18.
      • Making documentation more effective
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 19. How do you know?
      • How can you tell whether your documentation meets your readers' needs?
      • You can't follow readers into the workplace to see how they interpret your documentation.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 20. Quiz
      • Solution: offer users a short quiz (perhaps one to three questions).
      • Writing the correct questions is critical.
      • Questions should test essential concepts, not ask for the repetition of facts.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 21. Demonstration
      • Prototype of program that creates quiz.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 22. Suggestions Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 23. Suggestion: Upgrade submissions
      • Encourage contributors to turn valuable postings into web pages, turn large web pages into wikis, etc.
      • If a wiki, FAQ, or other formal document answers a question, always point the reader to it instead of providing a direct answer. This will encourage more contributions.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 24. Suggestion: Put in a reputation system
      • Rewards can be very simple: regular thank-you's to major contributors, or a most-prolific-contributor list.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 25. Suggestion: Teach how to do research
      • Novices need to learn what documentation exists and how to extract what they need from that documentation.
      • Veterans can train novices to use documentation effectively, in addition to providing direct answers.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 26. Suggestion: Professional editing
      • Bring in an expert to determine whether document:
      • States expectations
      • Provides background
      • Defines terms
      • Includes all necessary steps
      • Reflects common wisdom
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 27. Suggestion: Link in background
      • Provide a form with every web page where readers can suggest documents that provide additional information.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 28. Suggestion summary
      • Get organized.
      • Leverage the community.
      • Give documentation the attention and resources it deserves.
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007
  • 29. Further reading
      • Splitting Books Open: Trends in Traditional and Online Technical Documentation
      • http://opensource.oreilly.com/news/2004/09/23/online_trends.html
      • Rethinking Community Documentation
      • http://www.onlamp.com/pub/a/onlamp/2006/07/06/rethinking-community-documentation.html
      • Do-It-Yourself Documentation? Research Into the Effectiveness of Mailing Lists
      • http://praxagora.com/andyo/professional/mailing_list/mailing_list.html
      • Online documentation: what's missing
      • http://www.oreillynet.com/onlamp/blog/2007/01/online_documentation_whats_mis.html
    Andy Oram — Editor, O'Reilly Media Open Source Convention July 25, 2007