Radically open documentation


Published on

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

Published in: Technology, News & Politics
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • The web is too big for one company to document. It encourages contributions from user and developers of other browsers.
  • 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.
  • Need to offer examples of community contributors, including tools like trevor ’ s mdni and Florian ’ s doc tracker
  • IRC, email, mailing list
  • Accuracy: dated content, incorrect information, missing key details Editorial: Mis-filed or mis-titled articles, Poor formatting and layout, Bad grammar and spelling
  • The well-intentioned but wrong can be the worst of these because they ’ re hard to detect, and could be converted into valuable contributors sometimes, but it ’ s hard to be sure.
  • Tell the story of the guy who was hesitant to edit docs written by the guy that invented JavaScript.
  • Radically open documentation

    1. 1. Radically Open Documentation Eric Shepherd (@sheppy) Janet Swisher (@jmswisher) Mozilla Developer Network Session hashtag: #radopen
    2. 2. Why Be Open?
    3. 3. Why Be Open? <ul><li>The goals of being open are: </li></ul><ul><li>Participation : Rocket fuel for smarter collaboration. </li></ul><ul><li>Agility : Speed. Flexibility. Getting stuff done. </li></ul><ul><li>Momentum : Communities want to push boulders that are already rolling. </li></ul><ul><li>Rapid prototyping : Iterating and refining as we go. </li></ul><ul><li>Leverage : Getting greater bang from limited resources. Punching above our weight. </li></ul><ul><li>http://openmatt.wordpress.com/2011/04/06/how-to-work-open/ </li></ul>
    4. 4. Why Be Open? <ul><li>The goals of open are NOT: </li></ul><ul><li>Public performance Creating the fake appearance of consultation. </li></ul><ul><li>Endless opinion-sharing Never-ending “ feedback ” . Bike-shedding. </li></ul><ul><li>Magic “ crowd-sourcing ” Crowds aren't smart – communities of peers are. </li></ul><ul><li>http://openmatt.wordpress.com/2011/04/06/how-to-work-open/ </li></ul>
    5. 5. What is Open Documentation? <ul><li>For Mozilla Developer Network, it means: </li></ul><ul><li>Open to read (without login) </li></ul><ul><li>Open to modify (with login) </li></ul><ul><li>Open to copy and distribute (Creative Commons: Attribution-ShareAlike) </li></ul><ul><li>Open to remix (CC-BY-SA, again) </li></ul><ul><li>https://developer.mozilla.org/ </li></ul>
    6. 6. What Is MDN? <ul><li>Content </li></ul><ul><li>Web development: reference, tutorials, and guides </li></ul><ul><li>Mozilla APIs </li></ul><ul><li>Mozilla project (building, testing, debugging, process) </li></ul><ul><li>Firefox add-on development </li></ul><ul><li>Audience </li></ul><ul><li>Web developers </li></ul><ul><li>Developers using Mozilla code/libraries </li></ul><ul><li>Developers working on the Mozilla project </li></ul><ul><li>Add-on developers </li></ul>
    7. 7. Where Content Comes From <ul><li>Some historical content (e.g., inherited from Netscape) </li></ul><ul><li>New material </li></ul><ul><li>Some paid for by Mozilla </li></ul><ul><li>Some contributed by Mozilla community </li></ul><ul><li>Some from other communities </li></ul>
    8. 8. Documentation Process <ul><li>Using Bugzilla as a documentation planning tool </li></ul><ul><ul><li>Documentation-specific bugs </li></ul></ul><ul><ul><li>Tags on engineering bugs </li></ul></ul><ul><li>Prioritization and delegation </li></ul><ul><li>Tagging for review </li></ul>
    9. 9. Benefits of Open Documentation <ul><li>More contributors </li></ul><ul><li>Broader expertise </li></ul><ul><li>Engineers </li></ul><ul><li>Users </li></ul><ul><li>Casual readers </li></ul><ul><li>Localization </li></ul>
    10. 10. Engaging Contributors <ul><li>Multiple communication channels </li></ul><ul><li>“ Wiki Wednesdays ” </li></ul><ul><li>Community meetings </li></ul><ul><li>Doc sprints </li></ul><ul><li>Express gratitude early and often </li></ul>
    11. 11. Pitfalls <ul><li>Out-dated or incorrect information </li></ul><ul><li>Poor organization </li></ul><ul><li>Poor formatting and layout </li></ul><ul><li>Bad grammar and spelling </li></ul>
    12. 12. “ Villains ” <ul><li>Being open exposes you to potential villains </li></ul><ul><li>The spammer </li></ul><ul><li>The black-hat hacker </li></ul><ul><li>The troll </li></ul><ul><li>The well-intentioned but wrong </li></ul>
    13. 13. Why People Don ’ t Contribute <ul><li>They don ’ t realize it's a wiki </li></ul><ul><li>They don ’ t want to bother setting up an account </li></ul><ul><li>They ’ re intimidated by changing “ the ” documentation </li></ul>
    14. 14. Avoiding Pitfalls <ul><li>Vigilant content review </li></ul><ul><li>Good, easy-to-find guidelines and templates </li></ul><ul><li>Patience </li></ul><ul><li>Constant community engagement </li></ul>
    15. 15. Other Approaches <ul><li>Require a review before changes “ go live ” </li></ul><ul><li>Allow anonymous users to contribute but require vetting before changes go live </li></ul><ul><li>Allow comments but not direct edits </li></ul>
    16. 16. Signs of Success
    17. 17. Take Away <ul><li>Openness is a means to an end: Start from your business goals. </li></ul><ul><li>Contributions may come from unexpected quarters. </li></ul><ul><li>Open documentation is worth the occasional frustration. </li></ul>
    18. 18. Thanks! <ul><li>Eric Shepherd: sheppy@mozilla.com, @sheppy </li></ul><ul><li>Janet Swisher: jswisher@mozilla.com, @jmswisher </li></ul><ul><li>https://developer.mozilla.org/ </li></ul>