How can we integrate a lightweight public ticketing system into our documentation feedback form?
We publish a substantial documentation set online. Each page has a place at the bottom that asks "was this helpful? (Y/N)", and if the person chooses "no" we offer a textbox. We collect all this feedback internally (it feeds into our internal ticketing system, except for the spam), but to the user, it feels like typing feedback into the void -- you never know when there'll be followup. Further, because the communication is one-way, we can't ask people to clarify comments when needed.
We would much rather have a public tracking system for these issues, where the response to the form submission would include a link with an invitation to track this issue. (We'd rather not ask for email addresses; this should feel completely opt-in and safe to the person offering us the feedback.) We want to find a place to host tickets that the public can follow and that we can update (either to say we've fixed it or to ask for more information). I'm imagining that all of these tickets would be created by us (well, by our feedback system) in response to the in-doc feedback, at least initially.
What tools should we consider? Opening our internal ticketing system to the public is not an option.
If we were managing our code (or documentation) on GitHub then using GH issues for this would seem obvious, but we're not, so it feels strange to create a project just to "host" issues for some other system. We're a for-profit corporation, not a non-profit or open-source project, and we don't want to step on toes or give a bad look by misusing tools meant for a different context. We also don't have a lot of money to spend on this and need to keep administration simple.
3 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
Have you considered a simple comment system, something like Disqus. There is a certain amount of spam protection built into those systems, you can choose to moderate posts, and people can subscribe to comments on individual pages.
You could state your intention to remove comments once they have been addressed, or you could choose to leave them there if you think they provide useful redirection or simply demonstrate your openness to feedback.
This would not give you issue tracking in the conventional sense, though I think things like Disqus give you a dashboard that might give you some basic management capability. But it would give you the openness, and the ability for readers to track updates and receive notifications when their issues are addressed. (Maybe you post a reply to a comment when you address it and then take down the original comment after 30 days so anyone tracking it has has a chance to see it.)
0 comment threads
How to present the question
This section doesn't directly answer your questions, but address problems with such web pages that are all too common.
I'm one of those that pretty much never answers "Was this helpful?". Most of the reason a web page was not helpful is because a search engine directed me there, but it wasn't a match. It doesn't feel like it makes any sense to respond.
Another common reason is that I'm trying to understand what something is, but the site only gives me content-free marketing babble about how wonderful it is. Providing feedback to an image-over-value company seems pointless, and by treating me like a mark at a circus instead of a potential collaborator makes me feel like they don't deserve my volunteer help. What's in it for me?
(For a real life example of the above, go to the Adobe web site and try to actually understand what the various products do if you don't already know.)
Before you ask for a favor, you need to treat people with respect.
Consider asking differently. I think "How can we improve this page?" sounds better than "Was this helpful?". I can't explain why, but the first sounds better somehow.
Also, reduce the barrier to entry. "Was this helpful (Y,N)?" is bad because I have to click on "No" first to get anywhere. I'm thinking "What happens then? Too much hassle. Screw this.".
If on the other hand there was "How can we improve this page?" followed by a box I can directly type in, then I might just vent on what I didn't like. It's right there. I can see what's going to happen. All I need to do is start typing.
What to do with the responses
Have a public web forum. This can be useful for supporting your products in general. One section can be about web site issues. Somewhere in there is where the "How can we improve this page?" responses go.
The rest of the mechanics I'm not sure about. There are several ways to structure this. Probably only experience will tell you what works best.
For example, should there be a thread (or some collection) for each page that has a response form? It could be useful to see all the responses for a particular page in one place. That allows a link to that web forum section directly below the response box. This may make it more difficult to respond to individual suggestions, though.
Users that want to follow up would need to get onto the forum where they can participate as usual for a forum, including providing more detail on their own and other people's responses. Users can then opt-in to get notified about new posts in various sections or threads or whatever.
Why not email?
We'd rather not ask for email addresses; this should feel completely opt-in and safe to the person offering us the feedback.
I assume this is a totally open system - no "login" needed. Because if a login was needed then you already have email and/or other information needed to connect an issue with a user.
In a totally open system, requesting an email address is about as simple as you can get while still being functional. It is a lot less than "create an account". If people are uncomfortable with this they can either use a throwaway email address (which may be a one-time use and they check it if they feel like it (which you won't know), may be a bitbucket (and you won't know), or may actually bounce).
Use this address to:
- Send an initial confirmation.
Just "Thanks for submitting" followed by the text of their submission, followed by "We will notify you if we make any changes or have questions blah blah blah" and "Reply to this email if you have additional information" (the Reply address should be oursystem-12345@example.com, where 12345 is the issue #, which with a little programming can be used to automatically add the replies into your ticketing system).
This message and any future messages should include:
An Unsubscribe link so that if either the submitter doesn't want any more messages or the address was fake (effectively spamming someone else) that it can be removed from your active list.
and
A "view online" link. Since this is open stuff and not confidential, this can simply be a link with the issue ID # plus some sort of hash to prevent casual unwanted random access (12345 was my issue, I wonder what 12346 is...). Not a true "login" - that is more complicated than necessary here.
- Send followups if appropriate.
The message was an actual honest-to-goodness useful suggestion and you implemented the suggestion. Or it was a complaint about inappropriate text on the page and you removed the text. Or whatever. You might never send a followup - e.g., if the original user message was spam or "thanks" or "your system sucks" or simply an issue you don't want to deal with.
- Never, EVER send actual marketing emails.
Your messages (initial and followup) can, and should, include your company information, but since this list is not positioned as a marketing list, do not use it as a marketing list. It should never leave the appropriate support department except individual items to appropriate people as needed.
2 comment threads
0 comment threads