1. Open Documentation
Eric Shepherd (@sheppy)
Janet Swisher (@jmswisher)
Mozilla Developer Network
2. Questions welcome!
• What are you looking for?
• What problems are you facing?
• What do you hope to learn?
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
5. What is community?
“It is 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
10. Which comes first?
“The Apache 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
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 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. 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 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. Documentation process
• Bugzilla as 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
21. Why people don’t contribute
• 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 and villains
•Vigilant content review
•Good, easy-to-find guidelines and templates
•Patience
•Constant community engagement
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 people contribute?
“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”
• Positive Emotion and engagement
• Building positive Relationships
• Meaning: connecting to a mission or goal
greater than ourselves
• Accomplishment: opportunity to do
something that matters
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
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
Notes de l'éditeur
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 goalhttp://justwriteclick.com/2009/02/25/user-generated-content-versus-community-generated-content/
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?”
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.