Radically open documentation

Radically Open Documentation

Eric Shepherd (@sheppy)Janet Swisher (@jmswisher)

Mozilla Developer Network

Session hashtag: #radopen

Why Be Open?

Why Be Open?The goals of being open are:

•Participation: Rocket fuel for smarter collaboration.

•Agility: Speed. Flexibility. Getting stuff done.

•Momentum: Communities want to push boulders that are already rolling.

•Rapid prototyping: Iterating and refining as we go.

•Leverage: Getting greater bang from limited resources. Punching above our weight.

http://openmatt.wordpress.com/2011/04/06/how-to-work-open/

Why Be Open?The goals of open are NOT:

•Public performance Creating the fake appearance of consultation.

•Endless opinion-sharingNever-ending “feedback”. Bike-shedding.

•Magic “crowd-sourcing”Crowds aren't smart – communities of peers are.

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)

https://developer.mozilla.org/

What Is MDN?Content

•Web development: reference, tutorials, and guides

•Mozilla APIs

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

• Firefox add-on development

Audience

• Web 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

Documentation Process• Using Bugzilla as a documentation planning tool

• Documentation-specific bugs

• Tags on engineering bugs

• Prioritization and delegation

• Tagging for review

Benefits of Open Documentation

•More contributors

•Broader expertise

•Engineers

•Users

•Casual readers

• Localization

Engaging Contributors•Multiple communication channels

• “Wiki Wednesdays”

•Community meetings

•Doc sprints

•Express gratitude early and often

Pitfalls•Out-dated or incorrect information

•Poor organization

•Poor formatting and layout

•Bad grammar and spelling

“Villains”Being open exposes you to potential villains

•The spammer

•The black-hat hacker

•The troll

•The well-intentioned but wrong

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

•Vigilant content review

•Good, easy-to-find guidelines and templates

•Patience

•Constant community engagement

Other Approaches

•Require a review before changes “go live”

•Allow anonymous users to contribute but require vetting before changes go live

•Allow comments but not direct edits

Signs of Success

Take Away

•Openness is a means to an end: Start from your business goals.

•Contributions may come from unexpected quarters.

•Open documentation is worth the occasional frustration.

Thanks!

•Eric Shepherd: sheppy@mozilla.com, @sheppy

• Janet Swisher: jswisher@mozilla.com, @jmswisher

https://developer.mozilla.org/