Does it take a community to document a technical issue?
The technical writer profession takes it on the chin sometimes. So much so, community-based technical documentation – user forums, wikis, blogs, and other social media – is becoming a go-to source for technical documentation and training. On how to perform technical tasks and thus to open another front for criticism on the traditional role of the technical writer.
While even for me, Google is the first stop when I need to look something up or troubleshoot an issue, I then have to dig through a fair amount of crap to get verifiable technical, accurate information to help resolve my problem. Even vendor-sponsored user forums can get laborious unless I can find another user who has the same issue that I am encountering. I’m a quick hunter and gatherer of information. But what about less experienced technology users having to look something up online? My online first method of researching technical issues comes from following:
- Natural migration of user documentation from print to online (take for example Microsoft Office documentation on Office.com).
- Disappointment with vendor documentation.
- Language and cultural barriers to offshore technical support.
- Lack of access to vendor documentation when I’ve been on customer sites.
Community-based documentation is already taking a foothold with technology vendors – Microsoft and HP to name a few. The capturing of community knowledge on technology topics like configuring an HP printer to print wirelessly from Mac OS X can be quite powerful indeed. However, to make it work for the product and the users, there is a lot of work that needs to happen behind the scenes. For instance, technical writers aren’t going to be able to opt out of learning the technologies they are documenting. Mature processes –- not buzzwords — need to be in place to help cultivate the community-based documentation from degenerating into a morass of technical inaccuracies and fanboy flame wars. For a technical writer to have any substantive participation in the community-based documentation, they are going to have to have a grounding in the products and be able to capture the rest from subject matter experts inside their organization
Seeding a community-based documentation site with paid moderators (company employees or contractors) also seems to be a necessity. Community-based documentation as potential source material for traditional online help and documentation is also another exciting element to consider, but that is still going to require grounding in the product and a different shade of strategy than what is typically found in typical documentation plans. The strategy for community-based documentation shouldn’t just have a technical writer as a stakeholder/interested party; this list can include:
- Product management
- Technical support
- Professional services
Community-based documentation isn’t going to be appropriate for every audience. For example, if you work for a federal government contractor sharing technical information in an open online forum is a no go. Likewise, a free online venue isn’t going to be right for some in the medical and legal fields to share their technical issues and concerns due to reasons of compliance.
My luck with community-based documentation in the past has been with vendor-driven sites like MSDN blogs, WordPress online resources and some of the Microsoft forums.
While I like to see the gory details of troubleshooting processes, I’ve yet to see the community-based documentation that can substitute for technical documentation produced under traditional authoring processes.
So I ask again, does it take a community to document a technical issue?