I started working at Microsoft in January 2022. I enjoy it. I even wrote a stream-of-consciousness post about it last year.
A significant part of our job in the Database Docs team, is to resolve customer feedback issues about documentation. It doesn’t quite consume half of my time every month, but it might.
Feedback
Recently we switched from GitHub issues to a Unified User Feedback (UUF) model. UUF is an internal name, and it is a vast improvement on our old feedback system. We previously encouraged the use of GitHub issues because the old Feedback system was so limited. Now, when you click on Feedback (at the top or bottom of most Microsoft Docs articles, usually indicated with a thumb icon), you get to self-classify the issue, type in some text up to 999 characters, and vote up or down on it, before we see it. The classification option is what’s new, and helps dramatically with triaging issues. Another change is that all UUF items are translated into English, so we see and triage all of them.
A vendor team usually goes through these thousands of feedback items a week, filtering out the offensive ones that have no actionable feedback, and we end up with about 40 items a week in our team. Then once a week after our team meeting, we triage those assigned to us.
As I wrote on LinkedIn recently, I personally close about 25-30% of those as non-actionable. Reasons why we close UUF items with no further action are varied, but they often can be classified under one of the following options:
- The answer to the question is already there and you just didn’t read it properly
- We’re not going to add a screenshot to a reference article about Transact-SQL
- We’re not going to move Examples to the top of the article
- Your use-case is too specific and isn’t relevant to most of our customers (I call this the Stack Overflow reason)
- This is a support question and we can’t answer it
Quick resolution
For the ones I do accept, which can be anything from zero to 20 UUF items in a week depending on the content area, I look at the easy ones and try knock them out on the same day. These are articles that have typos, missing links, broken links, weird formatting, and basic problems that I don’t need someone else to help me with. After all, I do know a thing or two about SQL Server, Linux, and internals. That’s why you might see a lot of refreshed articles on Thursdays and Fridays.
Slow resolution
In the rest of this post, I want to explain what it is I actually do when we get a more complex issue through our UUF system, using a specific example. For legal reasons I can’t paste the text of the item, and given how our UUF system works, I have no idea who originally created the feedback item (it has to be anonymous: that’s one of the reasons we switched away from GitHub issues).
In this example, a customer stated that the Query hints article contains an error regarding behaviour of a hint as it relates to a similar trace flag. They provided a link to a blog post from 2017, written by a known Data Platform community member. For the purposes of this post, I’ll say that Data Platform MVPs (current and former), and former employees who write about the SQL Server Database Engine carry some cachet internally. That is to say, if you’re a name in the community, we look a little closer. (Full disclosure: I am a former MVP.)
I reached out to a senior program manager in the product group about this query hint and trace flag issue. There is a handful of PMs who carry a lot of knowledge about certain parts of the product, and if they don’t know the answer, they can tell me who to ask, or we can look in the source code.
For this particular example, we looked at the source code first. By all accounts, the UUF item was wrong: the source code showed that the query hint in question had the same behaviour as the trace flag. A naive read of the C method in question would read this (paraphrased) if-statement as unassailable proof:
if (trace_flag || query_hint) { /* do something */ }
This is Microsoft
But as I said, when the feedback is based off a blog post written by someone known to the product group, we dig deeper. In this case, the PM reached out to someone who would definitively know the answer. This is Microsoft after all: in a lot of cases, we can ask the person who wrote that code. As it turns out, Craig Freedman was able to respond to the PM and confirm that the claim in the 2017 blog post was correct, that the UUF item was also correct, and therefore that our documentation was wrong.
Two wrongs make it right
A side-effect of our new UUF system is that we can sort issues by article title. It so happened that a few other issues were opened regarding the Query hints and OPTION clause articles respectively, so I was able to correct two UUF issues, and use my DocsCleaner tool to refresh four or five articles in one go, all within the space of a couple of hours.
Satisfying? Absolutely. It’s tempting to want to close issues quickly as “wontfix”, especially if the source code “proves” it, but digging a little deeper, which took only a few extra minutes, provided us with an accurate update to the content, and at least one more happy customer.
Thanks for reading!