of 18 /18
Radically Open Documentation Eric Shepherd (@sheppy) Janet Swisher (@jmswisher) Mozilla Developer Network Session hashtag: #radopen

Radically open documentation

Embed Size (px)


What's it like to not just allow community contributions to your documentation, but depend on them? What if literally anybody could edit the docs and see your work as you write? Mozilla doc team members share their experiences working with radically open documentation for developers. Presentation by Eric Shepherd and Janet Swisher at the Technical Communication Summit, May 2011

Text of Radically open documentation

Page 1: Radically open documentation

Radically Open Documentation

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

Mozilla Developer Network

Session hashtag: #radopen

Page 2: Radically open documentation

Why Be Open?

Page 3: Radically open documentation

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.


Page 4: Radically open documentation

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.


Page 5: Radically open documentation

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)


Page 6: Radically open documentation

What Is MDN?Content

•Web development: reference, tutorials, and guides

•Mozilla APIs

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

• Firefox add-on development


• Web developers

• Developers using Mozilla code/libraries

• Developers working on the Mozilla project

• Add-on developers

Page 7: Radically open documentation

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

Page 8: Radically open documentation

Documentation Process• Using Bugzilla as a documentation planning tool

• Documentation-specific bugs

• Tags on engineering bugs

• Prioritization and delegation

• Tagging for review

Page 9: Radically open documentation

Benefits of Open Documentation

•More contributors

•Broader expertise



•Casual readers

• Localization

Page 10: Radically open documentation

Engaging Contributors•Multiple communication channels

• “Wiki Wednesdays”

•Community meetings

•Doc sprints

•Express gratitude early and often

Page 11: Radically open documentation

Pitfalls•Out-dated or incorrect information

•Poor organization

•Poor formatting and layout

•Bad grammar and spelling

Page 12: Radically open documentation

“Villains”Being open exposes you to potential villains

•The spammer

•The black-hat hacker

•The troll

•The well-intentioned but wrong

Page 13: Radically open documentation

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

Page 14: Radically open documentation

Avoiding Pitfalls

•Vigilant content review

•Good, easy-to-find guidelines and templates


•Constant community engagement

Page 15: Radically open documentation

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

Page 16: Radically open documentation

Signs of Success

Page 17: Radically open documentation

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.

Page 18: Radically open documentation


•Eric Shepherd: [email protected], @sheppy

• Janet Swisher: [email protected], @jmswisher