Stc tc open_documentation


Published on

  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • 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.
  • 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.
  • 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.
  • 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 goal
  • 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, 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?”
  • 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.
  • 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.
  • 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.
  • Other community content can be donated or paid for by other organizations, like Google or IBM.
  • 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.
  • Outdated or incorrect informationPoor organizationPoor formatting and layoutBad grammar and spelling
  • The spammerThe black-hat hackerThe troll and the grieferThe well-intentioned but wrong
  • If you build it, they might not come.Building a community is hard. Reaching critical mass is hard.
  • 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.
  • 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.
  • Game designer Jane McGonigal promotes the idea of “gamefulness”.You can strive to achieve a gameful community, regardless of whether you employ gamification.
  • 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.
  • Stc tc open_documentation

    1. 1. Open Documentation Eric Shepherd (@sheppy)Janet Swisher (@jmswisher)Mozilla Developer Network
    2. 2. Questions welcome!• What are you looking for?• What problems are you facing?• What do you hope to learn?
    3. 3. What we’re gonna tell ya• Ideas and definitions – Community – Community-generated content – Openness – Open documentation• Radically open docs on MDN• What you can do
    4. 4. WHAT IS ... ?
    5. 5. What is community?“It is not merely the group that generatescommunity, but the interactions within it.”―Jono Bacon, The Art of Community
    6. 6. Types of communityPlace Circu Interes (e.g., mstan Actionneighbor- 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. 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. 8. What CGC is NOT
    9. 9. What CGC is NOTPhoto by blmurch
    10. 10. Which comes first?“The Apache Software Foundation …believes that its first order of business iscreating healthy software contentdevelopment communities focused onsolving common problems; good softwarecontent is simply an emergent result.”―Brian Behlendorf, former president ofthe Apache Software Foundation
    11. 11. Why be open?
    12. 12. Why be open?Goals What it is not• Participation • Public performance• Agility • Endless opinion-sharing• Momentum • Magic “crowd-sourcing”• Rapid prototyping• Leverage
    13. 13. What is open documentation?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)
    15. 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. 16. Where content comes from• 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. 17. Documentation process• Bugzilla as a documentation planning tool • Documentation-specific bugs • Tags on engineering bugs• Prioritization and delegation• Tagging for review
    18. 18. Engaging contributors• Multiple communication channels• Community meetings• Doc sprints• Express gratitude early and often
    19. 19. Pitfalls
    20. 20. Villains
    21. 21. Why people don’t contribute• They don’t realize its a wiki• They don’t want to bother setting up an account• They’re intimidated by changing “the” documentation
    22. 22. Avoiding pitfalls and villains•Vigilant content review•Good, easy-to-find guidelines and templates•Patience•Constant community engagement
    23. 23. Signs of success
    24. 24. IN YOUR WORLD
    25. 25. Who is your community? General Public Customers Partners Engineering Tech Sales Pubs Support Consulting
    26. 26. Realistic expectationsPhoto by JoshBerglund19
    27. 27. Who will contribute?  90%: “lurk” but never contribute  9%: do a little  1%: do a lotJakob Nielsen, ParticipationInequality: Encouraging MoreUsers to Contribute Image by verbeeldingskr8
    28. 28. Why do people contribute?“Why do people contribute free documentation? Results of a survey,” Andy Oram
    29. 29. Challenges• Access –Who can see, contribute, approve?• Accuracy –How do you make sure it’s correct?• Authority –How can readers trust it?
    30. 30. Contribution ProcessWiki 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. 31. Paths to success• Welcome Wagon• Tasks for newbies• Multiple communication channels• Recognition and reputation• Mentor and empower• Gratitude• Recognition and reputation
    32. 32. Being “Gameful”• Positive Emotion and engagement• Building positive Relationships• Meaning: connecting to a mission or goal greater than ourselves• Accomplishment: opportunity to do something that matters
    33. 33. Take-awaysPhoto by renaissancechambara
    34. 34. Resources• The Art of 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• “Why do people write free documentation? Results of a survey,” Andy Oram free-documentation-results-of-a-survey.html• Reality is Broken: Why Games Make Us Better and How They Can Change the World, Jane McGonigal