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
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.