Three reasons you should allow comments in your documentation

Mil­lions of peo­ple around the world are post­ing blog entries and com­ment­ing on those posts. But tech­ni­cal writ­ers have remained on the side­lines by not let­ting our users com­ment on our content.

Here are three rea­sons you should enable commenting:

Rea­son #1: Peo­ple are used to writ­ing com­ments on blogs and web pages. Mil­lions of peo­ple post blog posts. And thou­sands of us add our com­ments to those posts. For the most part, tech­ni­cal writ­ers haven’t embraced this fea­ture. I’d haz­ard a guess that most online help or even sup­port web pages do not sup­port user comments.

I recent­ly read Clay Shirky’s book Cog­ni­tive Sur­plus. Shirky argues that in decades past North Amer­i­cans spent a lot of time watch­ing TV. But with the Inter­net, peo­ple are spend­ing much less time pas­sive­ly sit­ting on the couch. We’re par­tic­i­pat­ing online writ­ing blogs, cre­at­ing YouTube videos, and writ­ing and edit­ing con­tent on web sites like Wikipedia. Just a small change in how peo­ple spend their time can have aston­ish­ing changes in our world. He writes:
“Imag­ine that every­thing stays 99 per­cent the same, that peo­ple con­tin­ue to con­sume 99 per­cent of the tele­vi­sion they used to but 1 per­cent of that time gets carved out for pro­duc­ing and shar­ing. The con­nect­ed pop­u­la­tion still watch­es over a tril­lion hours of TV a year; 1 per­cent of that is more than 100 Wikipedias worth of par­tic­i­pa­tion per year.”

So the Inter­net has rev­o­lu­tion­ized how we spend our free time. As cit­i­zens and con­sumers, we are active­ly con­tribut­ing to con­tent. But tech­ni­cal writ­ers have remained on the side­lines by not let­ting our users com­ment on our content.

Rea­son #2: Col­lab­o­ra­tion helps cre­ate an online com­mu­ni­ty. Col­lab­o­ra­tion offers a num­ber of benefits:

* An online com­mu­ni­ty can help each oth­er share solu­tions, workarounds, and trou­bleshoot­ing tech­niques. Tech­ni­cal writer and author Anne Gen­tle writes in her book Con­ver­sa­tion and Com­mu­ni­ty : “…a com­mu­ni­ty of prac­tice can form now that online tools speed up the process of teach­ing spe­cif­ic tech­niques and learn­ing them from oth­ers.” Work­ers can spend about a third of their time look­ing for infor­ma­tion. An online com­mu­ni­ty is one of the ways that users can find infor­ma­tion quickly.

* An online com­mu­ni­ty builds good­will among your users. If your com­pa­ny has seri­ous­ly invest­ed a lot of time and mon­ey in an online com­mu­ni­ty with facil­i­ta­tors that respond help­ful­ly and quick­ly, the com­pa­ny slow­ly builds pos­i­tive good­will among its users. Over time, your com­pa­ny may be rec­og­nized as an inno­v­a­tive provider of support―potentially a dif­fer­en­tia­tor when com­pared to your competitors.

* An online com­mu­ni­ty can improve your con­tent. We all have blind spots. Maybe your online help doesn’t con­tain the key con­tent that users need. Per­haps they’re look­ing for specifics on a dif­fi­cult task. With an active and engaged com­mu­ni­ty, it won’t be long before some­one starts point­ing out the miss­ing pieces in your content.

Rea­son #3: Learn­ing new skills for writ­ers. Tech­ni­cal writ­ers are used to inter­view­ing SMEs, and draft­ing and edit­ing con­tent. By post­ing your doc­u­men­ta­tion and act­ing as a facil­i­ta­tor for user com­ments, you may learn about blog­ging soft­ware and HTML (depend­ing on which tool you use), and online diplo­ma­cy. Anne Gen­tle writes: “Con­sid­er becom­ing a mod­er­a­tor only after you have been a par­tic­i­pant for a while. Most online com­mu­ni­ties do not rec­og­nize any sense of enti­tle­ment that you may have because of your employ­er. Instead you must earn the community’s trust and offer real help, even if you only pro­vide links to your online help. Teach­ing the com­mu­ni­ty to fish (for infor­ma­tion) feeds them longer than just answer­ing ques­tions with­out cit­ing how you learned the infor­ma­tion yourself.”

Of course, I should point out that enabling com­ment­ing is no guar­an­tee of doc­u­men­ta­tion nir­vana. You may be sub­ject to spam­mers, your com­pa­ny needs to devote at least one per­son to mon­i­tor and respond to user com­ments, and you’ll prob­a­bly notice that a minor­i­ty of your users are the most like­ly to comment.

Here are a few exam­ples of online doc­u­men­ta­tion that encour­ages online dis­cus­sions and comments:

Microsoft’s Devel­op­er Net­work is one of the first exam­ples of com­mu­ni­ty-con­tributed content.
http://msdn.microsoft.com/en-us/library/ff851953.aspx#6

Atlass­ian allows users to post com­ments on its doc­u­men­ta­tion wiki.
http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home

On a relat­ed note, I wrote a blog entry about how to add com­ments to your doc­u­men­ta­tion using third-par­ty tools, such as Dis­qus and Wufoo.