Why you should allow users to comment in your software documentation

bri hillmer | August 28, 2016

Comments on the Internet are going the way of the dodo. In journalism, this is a fairly new trend.[1] In software documentation, comments often never existed.

The Benefits Of Allowing Comments in Your Software Documentation

As the title of this post suggests, I advocate for allowing users to comment on your documentation.There are a number of benefits of doing so.

1. Comments make users more likely to read your content. It's simple social engineering. When users can see that others have read and commented on a given article, they are more likely to read the content. It lends legitimacy to the content that an article with no comments could not.

2. Comments help other users. When you respond to comments with helpful responses the comment content itself might later help another user.

3. Comments improve search results. Comments are often phrased in the natural language of your users. When this language is indexed by search engines they can help other users get to the content that answers their questions.

4. Comments give you valuable feedback on how to improve your documentation. There's nothing harder than writing into a vacuum. Comments give you visibility into how readers use and experience your documentation. A thumbs up/thumbs down rating is simply not a substitute for comments.

5. Comments give you an opportunity to reward users for trying to help themselves.

Rewarding Users for Self-Service

I feel so strongly about that last benefit that I would like to riff on it for a bit;

In the SaaS industry, self-service is the promised land. As the name implies, the software is supposed to be the service. We dream of selling our software as the lone service, without needing to have support representatives to provide further service to support the software.

Whether or not this is a realistic or even desirable goal, it is almost universally true that SaaS companies are always looking for ways to reduce their customers' need to contact their support team. This is manifested in many different ways in SaaS companies resource efforts, but the first line of defense is almost always to give customers tools to help themselves. Official documentation is the most commonly provided self-service tool.

The last thing you want to do is discourage the use of self-service tools. As such, users who try to help themselves should be able to tell you when and why they couldn't.

Finally, as I'll discuss below, many of our commenters get speedy responses from me, speedier than what they would get from submitting a support request to our support team. This carrot encourages users to come back the next time they have a question, rather than giving up on your documentation altogether after failing to help themselves.

To Moderate Or Not

What is moderation? According to Stack Exchange, the defacto authority on user communities, community moderation is...

". . .the "cleaning up" of the site by users . . . It involves flagging, closing, commenting, editing, and sometimes deleting posts. It also involves "implicit" moderation — not doing anything considered inappropriate for this site . . ."

Fortunately, moderation in official software documentation comments is quite easy; it simply means does one approve/publish all comments, or not?

In my time managing documentation I have allowed users to post comments with and without moderation. I currently moderate all comments in our software documentation; here's why.

First, a portion of commenters posts comments/questions that are so specific they really should have been a support request. When this happens, I simply open an email ticket with the customer in order to gather additional information to help solve their problem. This is most expedient for all involved.

Second, sometimes I have no clue what the commenter is talking about. While I can certainly make an educated guess, it's most expedient for all involved if I open an email ticket with them so that they can tell me if I'm totally off the mark.

Third, reasons one and two make for a comment section that is most likely to be helpful to all readers.

Comments I Won’t Publish

What about comments from frustrated users? Complaints about a missing feature, our support hours, or a change to the user experience?

It depends.

I publish the majority of these kinds of comments. If the frustration is a common one, this is a great opportunity to offer all readers some visibility into why SurveyGizmo makes certain decisions.

"What if the commenter is REALLY frustrated?" you ask. Most of the time, I publish these too. It's great to have readers see you listening and empathizing, especially when you know the frustration is likely shared with other users. With these type of comments I also ALWAYS reach out to the customer personally (or have the support manager do so if that is more appropriate). If there's a phone number, we call it, otherwise, we reach out to them in an email. Frustrated customers need to feel heard; even if you cannot solve the source of their frustration, you need to show them you care.

So what comments don't I publish? They are few and far between, but if they are a certain kind of angry I will not publish the comment. There isn't a formula per se; I just know when I see a comment that shouldn't be published. Some comments are simply not constructive. Others might be embarrassing to the commenter once they've had some time to cool down. In short, it is a judgment call. But I always consult with co-workers before making the decision not to publish; then someone always follows up with that customer privately. Usually, it’s me, but sometimes it’s the support manager.

Features Your Commenting Platform Must Have

Now that I've convinced you to allow users to comment in your software's documentation, here are some must-have features to help you choose the right commenting platform.

Moderation

This functionality can take many forms. At the very least, you need to be able to delete a user's comment or decline to publish it.

Alerts for the moderator

The key to comments, if you are using them to encourage users to self-help, is to respond in a timely manner. Your commenting platform should have the ability to notify you that you have new comments.

A Subscribe option for commenters

Because you will be responding in a timely manner, you should have the ability for users to subscribe to the comment thread in order to receive a notification that you have responded.

[1] http://www.nytimes.com/roomfordebate/2016/04/18/have-comment-sections-on-news-media-websites-failed

{{snippet.BriHillmer}}

{{snippet.Disqus}}