Looking for feedback: Taking your software documentation to the next level

If you're writing documentation to help users help themselves (which, who isn't?) feedback is a really big gift. If you are writing agile documentation, feedback is essential for your success.

Feedback Sources

There's more feedback on your software documentation than you might think!

In a previous post, I made the case for allowing users to comment on your documentation. "Comments give you valuable feedback on how to improve your documentation," past bri wisely said.

Comments are just one way that you can gather feedback.

You can also gather feedback by creating a workflow so that your support team can easily and automatically send feedback (covered in more nitty-gritty detail in my Practical Guide to Agile Documentation).

Finally, you can look for feedback.

Combing The Support Queue For Documentation Feedback

On any given day, I spend about 15 minutes combing the support queue looking for feedback about my documentation.

Here's some feedback gold that I found in a ticket.

This issue involves two surveys . . . I am trying to pass multiple variables with a redirect . . .

The bug seems to be in the documentation "Send Values Through the URL Redirect Action". The instructions don't make sense so I'm not sure whether there is a bug in the software as well.

This article is not clear and seems incorrect. It first fails to mention that you need to set up a hidden value in the "redirected site" populated with [url("uid")]. I finally figured that out after several tries. Also, the directions for passing multiple variables makes no sense at all since they say to repeat the steps 1-7 which show creating a "new" URL redirect action each time. However within a single redirect action it show "Fields to Pass" implying one can pass multiple variables in this one redirect action. I've tried several times and cannot get a redirect action to pass more than one field.

Ouch! There's no mincing of words here. This feedback plainly highlights how my documentation falls short. The tone is a touch frustrated and rightly so; there's nothing more frustrating than trying to help yourself and having the available resources fall short.

Responding To Support Tickets That Mention Documentation

Because I have a workflow set up that allows support to get this type of feedback to me; I could very easily just leave this support ticket for a support hero to handle. But I don't. Here's why:

1. This feedback is so motivating for me. Nothing motivates me more than helping frustrated users, especially when I am the cause of it!
2. I caused this support. If the documentation were better this ticket may never have existed.
3. I will answer this ticket differently.

This is not to say that the support hero would not do a great job, but here's what's different about a response from me.

First, it is always great to hear from the source. For example, the article mentioned in the above ticket content was authored by me. So, I should be the one apologizing for the confusion and frustration it caused. Even if I wasn't the author, hearing from the documentation coordinator, conveys that the feedback is being taken seriously.

In addition, my response to the customer will have two goals. First, I will attempt to help the customer achieve their task. Second, I will attempt to find out from the customer what I can do to improve the documentation so I can help other users; some customers are game, some are not. Fortunately, in helping the customer, I can often achieve my second goal without any extra effort on their part.

I responded to the ticket like so:

My name is Bri. I am the documentation coordinator at SurveyGizmo. I am here to help (and fix up the document based on your feedback)!

This response dispenses all niceties and gets right down to the point. I've found this to be the best opening to a ticket like this. 

It worked and I learned a ton from responding to this ticket!

Some Improvement Metrics

This article existed more or less as is since 2013. Since the beginning of 2015, it averaged about 120 pageviews per month. It had an average rating of 2.25 stars out of 5. From this, I can conclude that 1) this is a tool that people generally want to use and 2) this document wasn't doing so well at helping them do so.

Now, you could argue that I should have noticed these statistics before the customer ever provided this feedback. In a perfect world, I would agree. But in my world, there's agile software. Where there's agile software, there must be agile documentation. Which often means improving documentation based on feedback like this!

Below are some metrics of the improvements I made to the document:

• + 403 words
• + 2 gifs
• + 1 example survey
• + 2 best practice tip
• + 2 new sections of content

Phew! That's a lot of improvements! Learn more about the specifics of the changes I made to the article based on what I learned from the customer.

+403 Words

More words are not necessarily better, but, when you're adding more words based on feedback, that's almost always a win!

+2 gifs^[2]

This is something relatively new that I've been doing that complements written setup steps quite nicely making them much easier to follow. This tutorial was begging for a gif or two!

+1 Example Survey

As a kinesthetic learner^[1] myself, I know there's nothing like experiencing something in action to understand how it works!

+1 Best Practice Tip

I use these throughout our documentation to prevent users from making mistakes or doing things that will make their lives difficult.

+2 New Sections of Content

Much of the 403 new words were devoted to entirely new sections of the tutorial.

The first is called "Capturing Values On The Other End." This was an awesome suggestion from the customer; in his words:

"The documentation doesn't mention how you get the URL at the redirect site although I guess it is implied." 

Eek! Nothing should be "implied" when it comes to software documentation!

Compatible Questions

The second new section covered SurveyGizmo question types that are compatible. Because, duh, this is important information! The customer also pointed out that I needed to address what happens when passing multiple data points, hence the asterisks noting how this works too!

If you are interested in seeing the article in its improved glory here it is; I think I rocked that feedback! What do you think?