Open Documentation Eric Shepherd (@sheppy)Janet Swisher (@jmswisher)Mozilla Developer Network
Questions welcome!• What are you looking for?• What problems are you facing?• What do you hope to learn?
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
WHAT IS ... ?
What is community?“It is not merely the group that generatescommunity, but the interactions within it.”―Jono Bacon, The Art of Community
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)
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
What CGC is NOT
What CGC is NOTPhoto by blmurch
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
Why be open?
Why be open?Goals What it is not• Participation • Public performance• Agility • Endless opinion-sharing• Momentum • Magic “crowd-sourcing”• Rapid prototyping• Leveragehttp://openmatt.wordpress.com/2011/04/06/how-to-work-open/
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)
MOZILLA DEVELOPER NETWORK
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
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
Documentation process• Bugzilla as a documentation planning tool • Documentation-specific bugs • Tags on engineering bugs• Prioritization and delegation• Tagging for review
Engaging contributors• Multiple communication channels• Community meetings• Doc sprints• Express gratitude early and often
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
Avoiding pitfalls and villains•Vigilant content review•Good, easy-to-find guidelines and templates•Patience•Constant community engagement
Signs of success
IN YOUR WORLD
Who is your community? General Public Customers Partners Engineering Tech Sales Pubs Support Consulting
Realistic expectationsPhoto by JoshBerglund19
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
Why do people contribute?“Why do people contribute free documentation? Results of a survey,” Andy Oram
Challenges• Access –Who can see, contribute, approve?• Accuracy –How do you make sure it’s correct?• Authority –How can readers trust it?
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.
Paths to success• Welcome Wagon• Tasks for newbies• Multiple communication channels• Recognition and reputation• Mentor and empower• Gratitude• Recognition and reputation
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
Take-awaysPhoto by renaissancechambara
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