docs.microsoft.com

Microsoft Learn GitHub and Feedback Updates

Posted on by Adam Fowler

Microsoft is changing the way feedback will be provided for Microsoft Learn content.

Microsoft Learn is an impressive resource for IT staff interacting with Microsoft technologies. It was first launched as docs.microsoft.com which came out all the way back in 2016. Before that, TechNet and MSDN were the sources of official Microsoft documentation, but they were incredibly lacking in both quality and quantity of information. It’s why most people relied on third party websites to find out how to ‘really’ do something in the Microsoft space – which is why it was great to see Microsoft spend time and money in something that gave them no immediate return on investment.

Microsoft Learn was built on customised GitHub architecture, allowing huge transparency on when documentation gets updated, what changed, and a way for customers to question and/or correct what they’re reading. It was also a pseudo feedback method where you could see what others may be complaining providing constructive criticism about when looking at a product yourself – similar to what Feedback Portal does for each product (which is still in beta, and replaced the decent third party UserVoice service) – but when you’re looking at feedback on a particular documentation page on a specific thing, the feedback you’re seeing is particularly relevant, rather than searching through an entire product’s history of feedback.

History lessons aside, Microsoft is now rolling out a change on how feedback works. It’s a bit of a mixed bag from what I can tell, so here’s the breakdown:

From the updated information on Provide feedback for Microsoft Learn content, there will be a few different options on what’s possible around providing feedback based on what page it is.

All pages will have the new feedback experience where you click the thumbs up Feedback button:

This will let you anonymously provide feedback. A single text box that you can write your thoughts on and submit into a black box:

I don’t like this because there’s no visibility, accountability, or any way I can actually engage with Microsoft. I can see why Microsoft wants this, but the old GitHub feedback method meant you could get a response, converse, clarify etc. That is completely gone with this method and personally I doubt I’d bother using it beyond a Yes/No response and maybe a 1 line. It doesn’t provide the customer with any real incentive to bother.

There is some good news however. Some pages will be configured to take you to the relevant Product Feedback page, and some will take you to a Q&A page for the product or community site. If these were widely implemented, it would go a long way to fill the above feedback gap.

Also, you can still use the pencil icon to submit changes and view page history… “for any repository that already had this capability enabled.“.

That implies any new repository (likely for any new product that doesn’t have it’s own content on Microsoft Learn yet) will not have this capability. Except, I can already see a repository that doesn’t have this capability – Purview related content. Check out any Purview page on Microsoft Learn such as Learn about data loss prevention | Microsoft Learn and you’ll notice there is no edit pencil, and feedback at the bottom of the page only has the new experience:

Compared to other pages such as this Publish on-premises apps with Microsoft Entra application proxy – Microsoft Entra ID | Microsoft Learn where the callout of the deprication of GitHub Issues is.

It is also worth noting that open source products will have a more open feedback experience using GitHub. A list of products that support this is available here and appears to be the same as the way we’ve been using feedback across the entire Microsoft Learn platform for a while.

Overall, I’d be guessing that the existing solution creates a lot of noise for Microsoft to manage based on the amount of feedback they’d get, and this is a way to stop it. If we see improvements in the other two-way feedback mechanisms, including Microsoft staff engaging more on these platforms, I can see it working well enough. Let’s hope that happens!

Update Microsoft’s Documentation Yourself

Posted on by Adam Fowler

This might be a strange concept to many people out there. Microsoft is letting you help correct/update/add to their online documentation at https://docs.microsoft.com

I’m typing this from Microsoft’s Headquarters as part of the MVP Summit, and the session is one of the few not under NDA which is a good reason to blog it :) Here’s my summary of the presentation:

Docs.Microsoft.Com is the new platform for Microsoft’s technical documentation across their entire product line for IT Professionals and Developers.

Why contribute?

To share your knowledge, help others and for Microsoft MVPs it adds to your contributions to keep the badge next year. This isn’t to do Microsoft’s documentation for them.

Where to start?

Start small – clarifications, examples (e.g. SDK/PowerShell), guidance tips and translations. If you see something wrong, fix it.

How to do it

You’ll need a GitHub account – https://github.com/join (don’t worry, you won’t need a client – this is all browser based).

Once you’re signed up, you find the article you want to change and choose the ‘Edit’ link on the top right below ‘Feedback’:

Then, you’ll need to click the pen icon (highlighted in yellow) to edit the actual text:

Now you’re able to change the raw text. The documents themselves are in Markdown. This means you’ll need to use characters to modify your text. For example **test** will come out as test. There’s a great cheatsheet here on lots of examples, but for starters follow what you can already see in the documentation rather than trying to create new styles.

You can use the ‘Preview’ tab to see the document with your new changes too. Once you’re happy, at the bottom of the page give a brief description of the change, and click ‘Propose File Change’

After that, you’ll see the final page which shows your change, and the button to ‘Create Pull Request’

You’re done! (For the most part). Your change gets sent off to the document owner for review. You’ll get some emails back advising of the progress, any questions/clarification and in the end, the change approved and your request closed.

It’s a very simple process while making sure the documentation is still Microsoft controlled. Get updating today!