User Comments and Feedback on Technical Documentation

June 20, 2012 at technical communication

Till few years back, the primary objective of technical documentation was to present the procedures and instructions clearly and accurately. Generally, the documentation team was lauded for doing a good job, as long as:

  • The page explained how to use a specific feature or how to do a task (such as to approve an invoice) with all required steps, the prerequisite steps, internal links for related topics, screenshots or location references, a well-structured TOC, and a comprehensive index
  • The language was correct, clear, concise and followed a well-defined style guide
  • The questions, concerns and doubts of the target audience were addressed most accurately
  • And, the topic met basic guidelines of a Help topic page layout (online or print)

I wonder if on one of those fine sunny days in December, I should have asked my documentation manager Seema, “Shall I ask the user if my instructions are clear, and that the information on that page is useful?”

It is not difficult to guess how she would have responded. May be “What does that mean? Why should we assume that user will say NO, that the information on page was not useful. Do we not trust our documentation skills?”

And I would have moved to my desk, quietly, acknowledging that it was indeed a stupid question. Why should I assume that a user can select NO option, for Was this information useful? And if I am expecting it, does it not mean that there are some issues in the documentation skills or in the process.

But it was many years back.

Today, I see that many online knowledge base systems have this option to ask users whether the information was useful or not. Some experts consider it as if we are evolving in our documentation practices and that seeking feedback is merely connecting with the users. Their take on why it is a good practice is:

  • Technical writers get to know what users do not understand. It helps the documentation team to update the documents accordingly. (I agree: The document is for users, and not for writers’ reference, and it is important to ensure that all users understand the instructions clearly and accurately. However, I am not sure if we can successfully draw the line between user expectations, user preferences, and user requirements.)
  • Technical writers get to know the user perspective on how they feel about the system when actually using the system. (I agree: Most often, the writers and test engineers are too close to the system that an external perspective is always welcome, and the actual users are best placed for that neutral perspective. However, I am not sure why technical writers cannot use the product from an independent user perspective.)
  • The result is a more accurate documentation. (It also means reduced number of calls to support team.)
  • Users feel that their feedback is accepted positively, and they feel good about using the product. And hence a positive opinion about the product in market. (I agree, again. However, I think that users will have an even more positive opinion about the product if the help topic is clear in the original version, without any need of user comments.)

Consider an example where a user comments that a particular procedure is not clearly explained, or that the invoice cannot be approved by following the listed steps. I wonder what signal it sends to the technical writer or documentation team (and to documentation QA team).

  • One, the documentation was not developed accurately in the first place, or it was not tested well, or both of these.
  • Two, the documentation team may be little relaxed during review/QA and final update, assuming that users are always there for comments.
  • Three (and all the more importantly), does it give some food for thought for the project development (or documentation) strategy, when (a) users comment on some gap in the application flow (b) 20% users say NO that a page is not useful and 60% users say NO to another page that the information is not useful. If it impacts the product development strategy, can we really rely on these numbers?

To Seek User Comments is different from Participative Documentation

Many writers in community advocate for *seeking user comments on HELP topics* because it helps users get involved with the documentation. In the same space, they emphasize that (a) the modern documentation practices call for seeking user opinion by polls and surveys, before the document is planned and after the document is available to them, and (b) users should be able to share the help topics on social media, and can even rate a page for usefulness.

I feel that seeking user comments on whether the information on a HELP page is useful, is different. It does not contribute to make the documentation participative, and the objective is altogether different.

My Take On This Practice

I am not interested to know users comments on the clarity of instructions, or whether the information was useful to complete the task. As a technical writer, I take it as my responsibility to ensure hundred percent votes as YES.

However, I may be interested to know user comments on the product feature or workflow, or for any gaps in application flow, or for general comments on the product. And for that, I am not sure if I should seek user comments on HELP topics. In addition, for general comments on HELP topics, we invariably have a dedicated page to contact the documentation team for user comments. So, why we need to ask users “Is the information on this page useful?”