Download to read offline
Uploaded byJanet Swisher
Stc tc open_documentation
This document summarizes key concepts about open documentation and community-generated content. It defines community as interactions within a group, discusses different types of communities, and explains that community comes before content. Community-generated content is defined as wiki-based documentation, comments, and forums. The document outlines why being open is important for participation, agility, and leverage. It describes the Mozilla Developer Network (MDN) as a resource for web developers that uses an open documentation model. Challenges of open documentation include getting people to contribute and ensuring accuracy. The document provides tips for avoiding pitfalls like intimidating new contributors and engaging a community.
Stc tc open_documentation
- 1. Open Documentation Eric Shepherd (@sheppy) Janet Swisher (@jmswisher) Mozilla Developer Network
- 2. Questions welcome! • Whatare you looking for? • What problems are you facing? • What do you hope to learn?
- 3. What we’re gonnatell ya • Ideas and definitions – Community – Community-generated content – Openness – Open documentation • Radically open docs on MDN • What you can do
- 4.
- 5. What is community? “Itis not merely the group that generates community, but the interactions within it.” ―Jono Bacon, The Art of Community
- 6. Types of community Place Circu Interes (e.g., mstan Action neighbor- t (shared hoods) ce (products, h goal) Positio (e.g., obbies) Purpos cancer n Practic survivors) e (e.g., teen e agers) (similar goals) (shared expertise & methods)
- 7. What is community-generated content? • Wiki-based docs • Comments on web- • Wiki-based knowledge based docs article • Comments on blogs • Open source docs • Support forums (parallel to code) • Sample code
- 8. What CGC isNOT
- 9. What CGC isNOT Photo by blmurch
- 10. Which comes first? “TheApache Software Foundation … believes that its first order of business is creating healthy software content development communities focused on solving common problems; good software content is simply an emergent result.” ―Brian Behlendorf, former president of the Apache Software Foundation
- 11.
- 12. Why be open? Goals What it is not • Participation • Public performance • Agility • Endless opinion-sharing • Momentum • Magic “crowd-sourcing” • Rapid prototyping • Leverage http://openmatt.wordpress.com/2011/04/06/how-to-work-open/
- 13. What is opendocumentation? For Mozilla Developer Network, it means: • Open to read (without login) • Open to modify (with login) • Open to copy and distribute (Creative Commons: Attribution-ShareAlike) • Open to remix (CC-BY-SA, again) (See the The Free Software Definition by GNU)
- 14.
- 15. What is MDN? Content Audience • Web development: • Web developers & reference, tutorials, and guides Web app developers • Mozilla products • • Mozilla APIs Developers using Mozilla code/libraries • Mozilla project (building, testing, debugging, process) • Developers working on the Mozilla project • Firefox add-on development • Add-on developers
- 16. Where content comesfrom • Some historical content (e.g., inherited from Netscape) • New material • Some paid for by Mozilla • Some contributed by Mozilla community • Some from other communities or organizations
- 17. Documentation process • Bugzillaas a documentation planning tool • Documentation-specific bugs • Tags on engineering bugs • Prioritization and delegation • Tagging for review
- 18. Engaging contributors • Multiple communication channels • Community meetings • Doc sprints • Express gratitude early and often
- 19.
- 20.
- 21. Why people don’tcontribute • They don’t realize it's a wiki • They don’t want to bother setting up an account • They’re intimidated by changing “the” documentation
- 22. Avoiding pitfalls andvillains •Vigilant content review •Good, easy-to-find guidelines and templates •Patience •Constant community engagement
- 23.
- 24.
- 25. Who is yourcommunity? General Public Customers Partners Engineering Tech Sales Pubs Support Consulting
- 26. Realistic expectations Photo byJoshBerglund19
- 27. Who will contribute? 90%: “lurk” but never contribute 9%: do a little 1%: do a lot Jakob Nielsen, Participation Inequality: Encouraging More Users to Contribute Image by verbeeldingskr8
- 28. Why do peoplecontribute? “Why do people contribute free documentation? Results of a survey,” Andy Oram
- 29. Challenges • Access –Who can see, contribute, approve? • Accuracy –How do you make sure it’s correct? • Authority –How can readers trust it?
- 30. Contribution Process Wiki Model Patch Model • Submit > Publish > Review • Submit > Review > Publish • Content is public • Content is not public until it immediately. is reviewed. • May want to visually differentiate unreviewed content. Or, allow comments but not direct edits at all.
- 31. Paths to success • Welcome Wagon • Tasks for newbies • Multiple communication channels • Recognition and reputation • Mentor and empower • Gratitude • Recognition and reputation
- 32. Being “Gameful” • PositiveEmotion and engagement • Building positive Relationships • Meaning: connecting to a mission or goal greater than ourselves • Accomplishment: opportunity to do something that matters
- 33.
- 34. Resources • The Artof Community: Building the New Age of Participation, Jono Bacon • Conversation and Community: The Social Web for Documentation, Anne Gentle • “Participation Inequality: Encouraging More Users to Contribute,” Jakob Nielsen http://www.useit.com/alertbox/participation_inequality.html • “Why do people write free documentation? Results of a survey,” Andy Oramhttp://onlamp.com/onlamp/2007/06/14/why-do-people-write- free-documentation-results-of-a-survey.html • Reality is Broken: Why Games Make Us Better and How They Can Change the World, Jane McGonigal
Editor's Notes
- #3 Group discussion is not very feasible in an online conference, but we’ll keep an eye on the chat window and try to address questions as they come up.
- #7 Wikipedia has separate entries for different types of communities, based on what brings them together. These include communities of:Circumstance: bound by circumstances, usually beyond their control (e.g., cancer survivors)Place: shared geographic locationPosition: shared station in life Interest: shared common interest (e.g., “I like product X”)Purpose: people trying to achieve similar goals (e.g., car-buying)Action: united by a shared goal (e.g., create an online encyclopedia)Practice: people who choose to collaborate over a period of time (often applied to professions or traditional crafts)Most communities around commercial products or services are communities of interest, which have fairly weak ties. Those ties become stronger if you manage to transform the community into one of action, practice or purpose. For example, draw your community into your organizational mission or vision.
- #8 Give me examples or definitions, whichever you prefer. We can extrapolate to definitions, based on examples.Examples: Comments on blogsComments on web-based docsSupport forumsWiki-based knowledgebases, wiki-based documentation – This is the one I’ll tend to refer to most, since it’s where I live.
- #9 Anne Gentle makes a distinction in her book, Conversation and Community, between community-generated content and user-generated content.User-generated content: all about me, single voice (facebook, flickr, twitter?)Community-generated content: collaborative, helps us reach our common goalhttp://justwriteclick.com/2009/02/25/user-generated-content-versus-community-generated-content/
- #10 CGC is not “crowd-sourcing”.You can get a crowd to do the thriller dance, or have a pillow fight, or kiss someone of the same gender while the Pope drives by. But you cannot get an anonymous crowd to create community content.“Crowds aren’t smart. Communities of peers are.” Matt Thompson, http://openmatt.wordpress.com/2011/04/06/how-to-work-open/Crowdsourcing is good if you have a large amount of small tasks, that people can work on pretty much independently.For larger tasks, especially where people need to collaborate, you need a community of individuals who have relationships with each other, not a crowd.This forces us to take a step back, and ask, “What is a community?”
- #11 This applies to content as well as to software.CGC helps create community by giving a group a shared goal. Getting useful content is a side-benefit.
- #13 Participation: rocket fuel for smarter collaborationAgility: Speed, flexibility, getting stuff done.Momentum: Communities want to push boulders that are already movingRapid prototyping: Iterating and refining as we go.Leverage: Getting greater bang from our limited resources. Punching above our weight.Public performance: Creating the fake appearance of consultationEndless opinion sharing: never-ending “feedback”. Bike-shedding.Magic “crowd-sourcing”: Crowds aren’t smart. Communities of peers are.
- #14 We (as employees) are peers with the rest of the community when it comes to creation and curation of content. Sheppy is “documentation lead” in that he tries to organize the content and project management side of things, and we are wiki admins because someone needs to be, but we are not the end-all of power on the site. Content Janet and Sheppy create goes through the same process, and carries the same weight, as anyone else’s.
- #17 Other community content can be donated or paid for by other organizations, like Google or IBM.
- #18 Note also that Bugzilla is open to everyone to read (with the exception of specific security bugs), and to edit with a login. Talk about Florian’s tool a bit.
- #20 Outdated or incorrect informationPoor organizationPoor formatting and layoutBad grammar and spelling
- #21 The spammerThe black-hat hackerThe troll and the grieferThe well-intentioned but wrong
- #27 If you build it, they might not come.Building a community is hard. Reaching critical mass is hard.
- #28 Do not be surprised or disappointed by this. If get a handful of people actively contributing, that can be a huge success.To get specific content written on specific deadlines, you usually have to pay someone. Your job is not at risk.
- #29 Number one is Personal Growth: wanting to learn something.Community is a bigger factor for documentors of free software, possibly because it’s explicitly discussed in free software contexts.A bigger factor for documentors of proprietary software is “thrills”: seeing your comments appear on a worldwide forum, as well as watching others succeed with your help and praise you for it.
- #33 Game designer Jane McGonigal promotes the idea of “gamefulness”.You can strive to achieve a gameful community, regardless of whether you employ gamification.
- #34 CGC is mostly about people solving problems; content is a side-benefit.Contributing to doc communities requires a healthy ego, neither too big nor too small.You don’t have to be open to the world to build a community around content. You can start by tapping expertise within your company.Most people don’t contribute, and that’s OK. People contribute for varied reasons: personal growth, gratitude, and thrills are high for those contributing to proprietary products.Make sure that communication channels exist for both content discussion and relationship building.