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 generates community, but the interactions within it.”―Jono Bacon, The Art of Community

Types of community

Action

(shared goal)

Circumstance(e.g.,

cancer survivors)

Interest

(products, hobbies)

Place(e.g.,

neighbor-hoods)

Position

(e.g., teenager

s)

Practice

(shared expertise

& methods)

Purpose

(similar goals)

What is community-generated content?

• Wiki-based docs• Wiki-based knowledge

article• Open source docs

(parallel to code)• Sample code

• Comments on web-based docs

• Comments on blogs• Support forums

What CGC is NOT

Photo by Global X

What CGC is NOT

Photo by blmurch

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

Why be open?

Why be open?

Goals• Participation• Agility• Momentum• Rapid prototyping• Leverage

What it is not• Public performance• Endless opinion-sharing• Magic “crowd-sourcing”

http://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• Web development:

reference, tutorials, and guides

• Mozilla products

• Mozilla APIs

• Mozilla project (building, testing, debugging, process)

• Firefox add-on development

Audience

• Web developers & Web app developers

• Developers using Mozilla code/libraries

• Developers working on the Mozilla project

• 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

Pitfalls

Image by @joefoodie

Villains

Photo by istolethetv

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

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?

Tech PubsSales

Engineering

Consulting

Support

Partners

Customers

General Public

Realistic expectations

Photo by JoshBerglund19

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

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 Process

Patch Model• Submit > Review > Publish• Content is not public until it

is reviewed.

Wiki Model• Submit > Publish > Review• Content is public

immediately.• 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-aways

Photo 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 Nielsenhttp://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