Sarah Maddox at Atlassian recently blogged about her experience with user comments on documentation:

There’s a lot to talk about: setting the permissions that determine who can add comments to the pages, managing those comments, the sort of comments people make, how many comments we receive, and above all, is it a good thing or a bad thing to allow public comments on the documentation?

Definitely check out her analysis, because it’s top notch stuff. She covers a lot of ground and provides a lot of examples. Ultimately, she’s enthusiastic about comments on documentation, but it left me wondering how that aligns with the expectations and perspective of documentation users.

My concern comes down to one statistic: 56%. Out 39 comments which appeared in a week, Sarah described more than half of those comments as “requesting support” or “requesting help on functionality.” Based on that analysis, it looks like the addition of comments to the mix has vague utility to users. Clearly users are seeing some kind of utility, but it looks like only a narrow majority actually see the same utility. Some use the opportunity to share tips or suggest documentation changes, most use comments as just another place to ask for help.

It’s not a problem per se. For Atlassian or any other organization, comments on documentation can be just another funnel for support requests. But I wonder how users regard that comment form. Are they seeing it as a place to literally comment, to wonder in public about their problems? Or are users seeing it as a close-proximity, low-friction way to reach out to Atlassian? In short, would a private feedback form built into the documentation be as successful as public comments?

Putting myself in the place of the user, I think a private feedback mechanism would be an improvement. When I want to bring something to the attention of the author of documentation, I don’t really care to see my name in lights—more so when it’s something negative—I just want to let them know. But sometimes public commentary is the only obvious path to do that and—particularly on blogs—I’ve opted to avoid the attention that might bring.