A New Feedback System Is Coming to docs.microsoft.com

This post was written by Rob Eisenberg, Senior Program Manager on the docs.microsoft.com team.

Microsoft's mission is to empower every person and every organization on the planet to achieve more. This was one of our considerations as we built docs.microsoft.com on top of the open GitHub platform. Today, we are taking it to the next level with the move to a new GitHub-based documentation feedback system.

Content Feedback on GitHub

While our documentation has been on GitHub since the beginning, our content feedback mechanism has been using Livefyre for comments on articles. While Livefyre is a great commenting solution, it turned out to be insufficient for our specific needs, which is to track, assign owners, and maintain the state of content issues raised by customers.

We explored a number of avenues to make it better, but one question that has guided much of our work seemed to resurface: If our documentation were treated just like open source code, what would we use to solve this problem? The answer to the question seemed obvious: GitHub Issues, so we began to experiment with integrating GitHub APIs more deeply into our documentation pages, being able to build a full feedback system on top of the GitHub infrastructure.

With the new system, you can now create GitHub issues directly from a content page, which enables you to interact in a much richer way with writers and product teams. See an issue with a document? A bad code sample? A confusing explanation? A critical omission? Just scroll to the bottom of the page and select Give documentation feedback.

You can see all open and closed issues associated with the document, directly from the documentation page itself - that way you are always in the know when things get fixed and resolved:

You can comment and even add reactions to issues that are important to you:

Now, Microsoft employees can leverage the full power of GitHub Issues to triage, respond, plan and fix reported problems - and you will always have visibility into the process!

Example documentation feedback

Let's say you file a GitHub issue for a broken hyperlink on an article. Our team will triage the issue, assign a label, and assign an owner to make the fix (or ask follow up questions). When the owner submits a pull request that fixes the issue, you'll be notified (based on your GitHub notification settings), that the issue has been resolved/closed, creating a virtuous cycle of feedback.

In addition, you can leverage all the standard GitHub goodness, such as Markdown in comments, subscriptions to individual issues or entire repos, RSS feeds of organization activity, @ mentions, assignees and more! We believe that deeper level of open source tool integration is going to foster new opportunities for community growth and collaboration.

Separation of Product Feedback

One of the issues with the previous system was the mix between product and documentation feedback in one stream - it was extremely hard to triage and follow-up, when not all items are consistently labeled. We took a step forward to fixing this problem by creating a clear way to separate the two:

By clicking Give product feedback, you will now be taken directly to the site where the product team associated with the specific documentation page handles product feedback.

Roll-Out

You might be wondering when the feedback system will be live. We've been piloting it for a couple months now for the Visual Studio IDE and the Azure CLI documentation. Starting in mid-February, we'll begin rolling this out across all of docs.microsoft.com.

Your Feedback

Your feedback is important to us, so we want to get this new system into your hands quickly. Though it is our next step in improving feedback and engagement on our platform, it is by no means our last step. Make sure to voice your thoughts about the changes on GitHub, or tag us on Twitter.