Should we allow comments on documentation pages

This is a very interesting question: Should we, as technical writers, allow comments on our documentation pages? It’s interesting because it’s a multi-faceted question, and because people have such strong feelings about it. My quick answer is, “Yes”. Ha ha, but there’s always a “but” or two. Read on, and then I’d love to know what you think.

I’m a technical writer at a company called Atlassian. We write all our product documentation on a wiki. For example, here is the Confluence user’s guide. What’s more, we have configured the wiki permissions to allow anyone to add comments to the pages. (We also allow known contributors to update the pages – but that’s another story.) Every now and then, the question comes up for debate again: Is it a good thing to allow comments on the pages? Up to now, we have decided each time to keep the comments. (Well, except for the developer documentation. More below.)

Multi-faceted question

We could rephrase the question like this:

Should we ask for feedback on the documentation? If so, are comments the best way of getting that feedback?

Or like this:

Should we allow everyone to comment on the documentation, or just known people?


What benefits do our customers get from being able to add and read comments on the documentation?


What benefits do we, as technical writers, get from the comments people add? And do we suffer any pain?


What  benefits does the organization get from allowing people to add comments to the documentation?

And so on.

Examples of comments

On the Atlassian product documentation, we allow everyone to add comments. Even people who have not logged in to the wiki – their comments  are recorded as “anonymous”.

Some comments are very relevant to the documentation itself. For example, the comments on this page about supported platforms in the Confluence administrator’s guide:

Some of the comments on the supported platforms page

Some of the comments on the supported platforms page

Other comments can be requests for help, or suggestions for new features or improvements in the product. Often a reader will add some information that will be useful to other readers. This one is on the page about configuring Tomcat’s URI encoding:

Page about configuring Tomcat's URI encoding

A reader offers information to others

Advantages of allowing comments

A quick list:

  • People tell us about errors or gaps in the documentation.
  • People use the documentation as a tool to help each other.
  • We learn about new ways that people are using our products, and sometimes even about new ways that they want to use the documentation.
  • The documentation becomes an active hub of interesting information. Readers receive notifications when other people add comments, and so keep coming back to the documentation to see the latest. The documentation sticks in their minds as a good place to find what they need.

Disadvantages of allowing comments

Another quick list:

  • Comments can make a page hard to read, if there are too many of them.
  • People may add worthless comments, spam, or even nuisance comments.
  • It is time-consuming, if not impossible, to respond to all the comments.
  • It is time-consuming, if not impossible, to clean up the comments when they are no longer needed. (But we could automate this.)

Please add a comment 😉 to this blog post, telling me what I’ve missed in these two lists.

No more comments on the developer documentation

A few months ago, we moved all of the developer documentation to a different wiki, the Atlassian Developers site. By “developer documentation”, I mean the API reference guides, the plugin development tutorials, and all the stuff related to developing add-ons and extensions for our products.

The developer documentation is still on a wiki. In fact, it’s a Confluence wiki just like the product documentation. But we have customised the look and feel, and added some plugins. The thing to note, from the point of view of this post, is that we have turned off the page comments. Instead, there are two panels at the bottom of each page:

Answers and feedback panels on documentation page

Atlassian Answers and feedback panels

The “Atlassian Answers” panel shows a list of posts drawn from a discussion forum called Atlassian Answers. The panel is supplied by a plugin for the wiki that hosts the documentation. The plugin matches the labels on the documentation pages to the tags on the discussion forum. The matching process is not perfect. In particular, labels and tags are not the most reliable way of matching content from a discussion forum and a documentation site. We plan to improve this, by a smarter matching of page titles and content.

The “feedback” panel is supplied by another plugin. When a person clicks “Yes”, “Somewhat” or “No”, a dialog appears where they can give us more information. The plugin posts an email containing that feedback, which in turn triggers the creation of an issue on our JIRA issue tracker. The technical writers and developer relations team can then assess and react to the feedback.

Comparing comments and feedback forms

An advantage of comments over feedback forms is that readers can see and respond to each other’s comments. People can benefit from the advice of other readers. They can hold a conversation and help each other solve problems, quite independently of the documentation authors.

Comparing comments and discussion forums

An advantage that comments have over discussion forums is that the comments are right there on the relevant page. People do not need to go looking for them on a separate discussion site. The information in the comments complements what is on the page.

On the other hand, a discussion forum is in itself a repository of information. I guess, as a technical writer, I’d like to keep people’s attention on the documentation. I’d prefer it if the docs did not become a dead site, for reference only.

But what serves the customer better?

What do you think?

Heh heh, it’s a complex question. And now let me add this specific question to the list: Would you cry if we removed the ability to comment on the Atlassian documentation in particular? (This is just a general question. There are no definite plans at the moment to remove commenting.)

Let the comments begin. 🙂

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 7 January 2012, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , . Bookmark the permalink. 11 Comments.

  1. Sarah,

    My answer is yes, you should allow comments on the docs. But it is a qualified yes, because I think allowing comments on docs should be part of a larger strategy — a strategy of engagement with the customer.

    One of the things I find about technical proposals of this sort is that they are always an expression of an underlying strategic vision, and that the arguments for and against such proposals are really arguments for or against that strategic vision, even if no one actually articulates the vision itself. Your list of disadvantages show this:

    Comments can make a page hard to read, if there are too many of them.
    People may add worthless comments, spam, or even nuisance comments.
    It is time-consuming, if not impossible, to respond to all the comments.
    It is time-consuming, if not impossible, to clean up the comments when they are no longer needed.

    What all of these objections really say is, engaging with customers is messy and time consuming. If you accept that a policy of engaging with customers is good for the company overall, then you accept that some customers will say things you don’t like, that you have to put up with that, and that you have to devote time and resources to the engagement, or it will wither on the vine. The real issue is to engage or not to engage; comments on the docs are an implementation detail.

    The problem is, if you don’t address the underlying strategic issue and make a firm decision on it, the individual engagement tools — like comments on the docs — become pawns in an ongoing strategic debate. I know of one company, for instance, the put it docs on the Internet for, I think it was, five weeks, before putting them back behind a firewall when another department objected. That sort of thing does no good for your relationship with your customers.

    So, the question you really need to ask yourself is, does my company want an open engagement with its customers, and have I got everyone on board with what that means and committed to providing the time and money to support it?

    The answer to that question could be very different for a company that makes five dollars from a million customers, one that makes a million dollars from five customers, and one that makes a thousand dollars from 5000 customers. The first probably cannot afford it, the second probably prefers person to person contact, but the third might find it the ideal strategy.

    So, I’m generally for an policy of engagement with customers, and for comments on the docs as an integral part of that strategy, But I am not for writers taking a flier on comments in the docs where the company as a whole is not committed to a strategy of customer engagement.

    • Hallo Mark

      A great comment, as usual. I love the clear perspective you bring to blog posts around the web! You’re right in saying that the organisation’s strategy of engagement with the customers is paramount.

      An important aspect is that the technical writing team will need the support of the organisation as a whole, in managing and responding to comments. Most technical writing teams are small in relation to the rest of the organisation. Many of the comments that come in are requests for help, rather than information specifically related to the documentation. It’s a good idea for other teams to be involved, such as the support engineers and product managers.

      Teamwork and engagement is all, both within and outside the organisation. A messy business indeed. Love it. 🙂

      Cheers, Sarah

  2. One other thought: a feedback form is customer data gathering, not customer engagement.

  3. Microsoft uses “Community Content” in their api documentation. Anyone can add content. Changes are available immediately, although the site is moderated. Here is a brief FAQ describing it:

    I’ve found additional community added examples and comments there very useful in the past.

  4. Great article, Sarah. I agree completely with Mark’s comment, as it echoes what I hear at my office frequently – which is, “Doesn’t social networking take up so much of your time?”

    The answer is yes and I welcome it.

    I think it’s important for everyone to accept no product is ever ‘perfect’ – not the code, not the documentation that accompanies the code, and not the systems and processes we use to deliver them. On-page-comments is merely one mechanism (that should be) in a larger strategy, as Mark suggests, for soliciting customer feedback that will be implemented in some way… even if it’s just an acknoweldgement. That needs to be everyone’s job.

    • Hallo Patty 🙂
      Yes! What’s more, technical communicators can show the rest of the organisation how this type of customer engagement can work. The documentation becomes a valuable part of the customer engagement strategy and the technical writers play a leading role in shaping and Carrying it out. It’s all in the communication.
      Cheers, Sarah

  5. I like the rephrasings of the question until you get to “who benefits” and Mark’s comments about having a clear goal make sense to me. I’m involved in the community Sarah is referring to. I like the new, cleaner pages without comments but wish there was a way to tie specific public feedback to a specific developer page. The answers site uses very generic tags such as “jira-development”, so I fear developer feedback is being lost at the moment. The next hard question is what’s the best way to gather feedback on a document – comments, a bug, maybe even email.

  6. Thanks for this insightful post! Here are a few specific questions for you:

    – I’m impressed by how you were able to transform your developer documentation into a developer portal. We’re looking to do just that as well. Any tips on where I can find guidance for tweaking Confluence wiki look and feel to that degree?

    – You mention that a plugin is behind the “feedback” panel in your developer portal, but you don’t name the plugin. Can you share that information?

    • Hallo Jesse

      Thanks for your nice words! The look and feel of the Atlassian Developers site comes from the Zen Foundation theme. It’s a Confluence plugin:

      Alas, the feedback plugin is not publicly available. It’s still undergoing development. I believe that the plan is to make it available at some stage, but it’s not ready for that yet.

      Cheers, Sarah

      • Thanks for your response, Sarah! I’ll check out the Zen plugin and hope that the feedback plugin goes public soon.


  1. Pingback: Procedure Writing for the ‘Masses’ | ENCORE Insights

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: