Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.

Feedback Handling, Community Wrangling, Panhandling

by Chris Mills

Slides

The context of this conversation is the large documentation project for the Mozilla Developer Network.

Feedback Mechanisms

How do you collect feedback from your community? There are lots of options each with their own pros and cons.

  • Email

    Pros:

    • old school
    • ubiquitous
    • you can share a lot
    • easy to funnel and separate
    • community involvement is easy

    Cons:

    • it is not sexy
    • often slips into one-to-one conversations
    • it can take you away from the docs (it is separated from the docs and can be disruptive)
  • IRC/Live Chat

    Pros:

    • synchronous communication is useful for immediate help
    • leads to rapid fixes
    • nice to talk to real people
    • strike up a relationships
    • community involvement is easy

    Cons:

    • sharing is more difficult
    • not persistent
    • IRC seen as archaic and geeky
    • harder to filter or scale
  • Forums (talk pages and wiki discussion pages)

    Pros:

    • closer to the docs
    • good for sharing lots of information
    • lower effort than sync
    • maintains history

    Cons:

    • require constant curation to avoid rot
    • can turn into documentation
    • can be harder to search, especially within conversations
  • Social Media

    Pros:

    • low effort and pressure
    • high coverage and engagement
    • great for marketing and promotion
    • can be great for quickfire asks

    Cons:

    • not good for conversation or contributions (structure is really not present)
    • focus can shift quickly
    • can be low signal to noise
    • can become toxic, often quickly
  • Issue Trackers

    Pros:

    • great for sharing details
    • conversations
    • community involvement
    • has search and history
    • information rot not as problematic (things get closed)

    Cons:

    • can pull you away from the docs
    • can be intimidating to non-techies
    • requires engineering overhead and can be overkill
  • Community Events

    Pros:

    • great for making relationships
    • great for deep understanding
    • high quality feedback
    • high signal to noise

    Cons:

    • costly
    • time consuming
    • digesting everything is scary
  • Automated Feedback

    Pros:

    • can be unintrusive especially for testing
    • very low to no ongoing effort
    • great for collecting very specific data

    Cons:

    • not useful for other types of data
    • initial engineering overhead
    • lack of contribution or relationships

Enter the Mozilla Developer Network

MDN is documenting the web platform and Mozilla internals. They have a paid writing team of 6 and a global volunteer community of 1000 monthly contributors. They get 4.5 million readers per month and lots of page views.

Some stuff works:

  • mailing lists
  • IRC
  • Bugzilla
  • A/B tests and quickfire questions
  • social media

Some stuff hasn’t worked:

  • comments on pages
  • talk pages
  • separate forums
  • other separate channels like Reddit

The theme of the stuff that doesn’t work is that it typically requires curation and/or is located in another “place.”

Responding to Feedback

The workflow through Mozilla can be described as a fire hose. So. Much. Work. Drowning in work. The result is that prioritization is critical.

Their main collection tool is Bugzilla. They have both their own bug products and a keyword to drive developer bugs that need docs.

They have a roadmap of prioritized major tasks. They also maintain a collection of “papercuts and isolated fixes” that are grouped and arranged into a single big bug.

Working on Things

It is a balancing act. Major releases and fixes get assigned to writers and completed in sprints. Random stuff is accomplished in spare time. The backlog list keeps growing.

Turning Feedback into Contributions

It is tricky!

However, it pays off. Almost all non-English pages are worked on by volunteers. While over half of all volunteers make a single edit, together the volunteers do three times the work of paid staff.

How do you Improve Contributions

You can’t just say, “It’s a wiki, edit it yourself, dumbass!” You can’t just put a big edit button. You have to be kinder.

Be Nice

  • Don’t be too pushy
  • Big tasks do not generally work with volunteers. Make things small.
  • Keep tasks granular so they don’t block.
  • Make it easy to find tasks (Trello, BugsAhoy, etc.)

Harness People’s Passions

They may have a specific area of interest or technology lean, they may have a school project (do the work and go), they may just want the free T-shirt. It doesn’t matter why someone contributes, you want the contribution.

Mentoring

Mentoring helps a lot. Just take it slow and be realistic. Teach the system as needed. Don’t scare people.

Keep People Engaged

Communicate with them. Hold regular meetings. Let them know you appreciate their work. Consider rewards or gamification.

Don’t Profile

There are lots of types of contributors. Accept them all. Reviewers and editors, bug fixers, spam fighters, structural updaters, etc. They all have their place. Spread the word to let them know you need them too.