Friday, October 02, 2020

Open Sourcing of PowerShell Documents is Awesome

Ever since the very first version of Windows PowerShell, the built-in help material has been awesome. Each cmdlet carefully documented with good examples to illustrate the most common use cases. Good English writing as well as best-practice PowerShell.

But every now and then there is an error. Some simple, some more complex. Some occasionally have some less than great grammar or miss out a useful example of the cmdlet. In the old, old days, you could file an issue somewhere that no one ever seemed to read. And then wait a year or longer before the next version of Windows PowerShell. It used to drive me nuts. I did rant a bit at the time (sorry Erin).

Then someone decided to Open Source the documentation and move it all to docs.microsoft.com. What a great idea. At first, it was a bit clumsy, as everyone involved slowly moved into the wonders of managing a complex repository at GitHub. The process was, again at first, a tad convoluted and frankly slow. BUT it worked. 

I recall the first time I saw an error. It was in class at Lab Center in Sweden. I was showing the delegates how to read the help text. A cmdlet parameters description said it did not take wild cards, but it did. Sok, in class, I filed an issue, edited the document, and issued a pull request. It was really cool although it took weeks to action.

Today, I saw an issue that arrived in my email in basket. You can read the issue on https://github.com/MicrosoftDocs/PowerShell-Docs/issues/6697. That message hit my email box at 7.23 this morning. I read it just after 10/ A few minutes later, I had edited the document and created a pull request. A 13:30 or thereabouts, I got an email to say that the issue was now closed as the PR had been accepted. 

So 6 hours from the time I got the email till the issue was resolved. It is going to take a few more days for the update to hit the web site, but I can live with that. 

TL;DR to me is that with the open sourcing of PowerShell documentation, errors need not persist. You can fix them easily. Or just report and let the community do the work. 

No comments: