Community collaboration is key, for the reasons I've mentioned in previous posts. But getting good collaboration isn't straightforward. You have to architect the site correctly, accommodating the reality of different collaboration types. You also have to guide the dynamics of a community in order to expose the useful feedback and prevent the entire site from being overrun by trolls, bad information, and Viagra commercials.
There are a couple of different models for encouraging community feedback.
Letting people add notes to the doc
One model is to maintain a canonical, source controlled doc, but let people add notes to the end of each doc page. php.net is an example of this model can work. As illustrated by the page I linked to, what makes this work is that contributors post useful information at the end of each page. The community-contributed content adds to what is already in the documentation, and is helpful to the wider community.
One advantage of this model is that it opens the docs up to collaboration, while ensuring the quality and reliability of the canonical docs. This offers protection against trolls, and also against people who have good intentions, but are just wrong.
The disadvantage of this model is that it usually garners a different type of feedback than you'd want. Users generally treat the comments section at the end of a page as either a forum, or as a place to give feedback about the docs. At best, community feedback generally consists of something like, "I'm trying to do X, please help" or "This page states that this method returns A, but it actually returns B. Please fix the doc." At worst, the feedback areas end up being a dumping ground for spammy links to online pharmacies and porn sites.
The way you get around this is to heavily moderate contributed comments, and address and remove those that aren't appropriate. Over time, the hope is that the docs will get enough appropriate comments that people will use those as an example, and begin to post the kind of thing you're looking for. Regardless, this will always require some moderation effort.
In my opinion, your best bet with this model is to bypass it altogether. Instead, link to a dedicated forum where people can garner answers from the community, and link to an issue tracker where people can report issues with the docs. If that's what people want to do, it's better to just accept it and provide appropriate tools to help.
Letting people modify anything in the doc
A second model is wiki, which opens up the docs entirely to community collaboration. The community can modify anything at all. developer.mozilla.org is an example of this model. You can access the collaboration history of each page by selecting "This page -> History" in the upper right hand corner. The history for the page I linked shows extensive community collaboration. Wikipedia is another well-known example of this model.
Usually, contributors are required to sign in before they post. Contributions can be reviewed by a central moderator, or by the community, or both.
Generally, as a contributor gains more credibility over time, their posts are subject to less oversight. Often what you end up with is a set of trusted core contributors, who are enthusiastic and familiar with the technology. You also have a long-tail of one-time or occasional contributors.
I think this model is where the documentation industry is going, and it's generally a good model to adopt. There are a few things you need to do to make it successful, though.
First and foremost, recognize the value of your top contributors. Give them some way to earn a public reputation on the site. Include them in events (either as attendees or speakers), send them t-shirts, give them early access to your APIs. As Pamela Fox mentioned in her post "How to Alienate a Community 101", though, you have to be careful that you do this in a way that recognizes the spectrum of contributions. Pamela's post contains good information about how to do that.
Next, adopt a good model for moderating content. The most sustainable way to do this long-term is to let the community moderate. Have a voting system, and use votes to flag content that needs to be reviewed. Allow access level based on reputation, so those users who are most helpful in the forums have the most leeway to modify the docs. Even if you do these things, though, recognize that you'll still need to put some work into moderating content in the short term.
Mindtouch, and Confluence are a couple of out-of-the-box solutions for this model. I haven't worked with either one so can't comment on their effectiveness.
Encouraging, and linking to, discussion in a forum
Embrace the fact that much of the useful hands-on discussion occurs in forums. There are several good sites for this, but one of the best sites I know of is Stack Overflow. It is already in wide use, for good reason. It supports reputations and badges, which makes for a good contributor experience. It supports tags, which is useful for finding and linking to relevant content.
If conversation about your product is happening in one of these forums, link to it. If not, encourage conversation there.
No comments:
Post a Comment