Github

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!

MSPortals.io – A List of Microsoft Portals

Posted on by Adam Fowler

I thought I should write up a little bit of information on a site I created; msportals.io and how it’s doing:

Being a Microsoft 365 Administrator at the time, I was looking for a list of all the Microsoft portals, particularly from an administrator point of view. A lot of lists were floating around, but nothing that was being maintained or comprehensive enough. I’d asked around a lot around it, others had the idea that they were going to create something – but nothing happened. It was a pretty simple idea and I was hardly the first to have it…

I also had the idea of creating this list on GitHub. I’d already been looking at GitHub Pages to move my blog to, but not being a programmer or developer, I was finding it too difficult to try and work out how to migrate and have feature parity with what I was using on WordPress. However, the GitHub Pages free tier, allowing 500mb of data in a public Github Repository sounded like a perfect fit for me, providing a platform for a list of URLs.

I started to collect and write up a list of portals. Just the name of the portal, and a link to it. I wasn’t using any GitHub client or command line things, purely using the web based interface for GitHub to start putting data in and seeing how it looked on the resulting msportals.github.io site. It seemed fine, so I started asking around for people to tell me of any links I might be missing. People jumped on board pretty quickly to help (read my thanks section here) to provide portals, but also to actually contribute to the project and provide features that would have taken me a very long time to work out myself.

I also bought a domain – msportals.xyz as it only cost a few dollars a year, and GitHub Pages supports bringing in your own domain. I had the site up, started using it.. and though I should throw it out there to see how much criticism it brought. I posted a tweet:

I didn’t expect to get much of a response – it was more of a test so I could properly launch later. Instead, as I expect what often happens on projects like this, it blew up. It turned out to be my most popular tweet of all time, with almost 100k views. My only annoyance of this was that I had no statistics to collect on how much the site was being used! Quickly I had help to add in Google Analytics to the site, so about a week later I had stats.

Since mid November 2020, the site has had 55,000 users hit it. As expected, the engagement time is tiny – you go to the site and click a link.

That peak is when The Register wrote an article on the site. The site changed from msportals.xyz to msportals.io after @SwiftOnSecurity bought it and handed it over, after some discussion around certain firewalls blocking xyz domains under some standard settings:

Updates and suggestions to the the portal of Microsoft portals came think and fast for a while – nice features like a filter so you can just type ‘teams’ and see the link to the Teams portal were implemented by others (mdjx), due to the way open source platforms like GitHub work.

I don’t see as many portal suggestions and updates these days, but they still trickle in. I still use the site frequently, and see people pop up time to time saying how much they like it which is awesome to hear; I really wanted something functional for myself, and if others also liked it, that was a bonus.

I actually had an idea for another site – a list of PowerShell modules with the commands to both install and connect to different things like Exchange Online and Microsoft Teams. Someone had beaten me to it (which is good!), and had done it a similar way; check out https://msshells.net/ by Andrés Gorzelany to have a look at what he’s done.

If you’ve got your own idea for something like this, go for it! You can do it entirely for free if you don’t care about your own top level domain, and it’s an interesting project to try.

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!