Considerations when writing a PowerShell blog

Summary: Microsoft Scripting Guy, Ed Wilson, talks about some specific considerations in regards to writing and reading Windows PowerShell blog articles.

One of the things that is cool about Windows PowerShell is that code seems to live forever. I mean, once I write a script, I can use it again and again and again. This can become a problem with Windows PowerShell however, because code does live forever … even bad code. Or maybe just code that was a workaround in Windows PowerShell 1.0, but now there is a better way to do things.

This is actually a problem with Windows PowerShell … in trying to keep up with documentation. For example, I may be looking for how to create a custom object in Windows PowerShell, and so I do a Bing search, and lo and behold I find some code written from maybe six years ago. There is no “versioning” in the code, or an “Applies to” in the blog article, so I copy the code and sure enough it works on my Windows PowerShell 5.0 Windows PowerShell ISE on Windows 10. Everything is groovy, right?

The problem with blog articles

Well, perhaps it depends on your definition of groovy. The code may very well still work, And, there are also probably five newer ways of creating a custom object from within Windows PowerShell code. Is that a bad thing? In my mind, not necessarily. From a learning perspective, maybe … probably. Because we add newer capabilities to Windows PowerShell with every revision, there are certainly easier, ways to accomplish the same task in Windows PowerShell 5.0 as there was in Windows PowerShell 1.0. But if the old code gets the job done, then what is the harm?

The biggest problem, is the way that search engines index. They take things like number of hits, links, updates, comments and the like into consideration, and more than likely a popular article written six years ago will have more search entropy than an article published last week about one of the latest features that would simplify the technique in the older article. Also, because the older article has greater search entropy, it continues to get more and more hits and therefore to remain higher in the search rankings …

So one always needs to look at when an article was published.

Well, what about “applies to …” Well, suppose that I wrote that article many years ago and had “applies to Windows PowerShell 1.0” in the tag line of the article. One may very well see the article, and note the absence of applies to Windows PowerShell 2, 3, 4, 5 etc. and think, this article is out of date and therefore won’t work.

Recommendations for users

But what if that article is about one of the edge cases that is, unfortunately, still the way that you have to do things even in Windows PowerShell 5.0… then what? Here are a couple of recommendations from a user perspective:

1. Always look to see when the article was published.
2. Always look to see if there is an “applies to” or version tag attached to the article.
3. Of course, see if you are on a reputable web / blog site.
4. Look over the code and see if it makes sense.
5. Try the code out … use -WHATIF if possible to see what the code will do.
6. If the code seems ridiculously complicated, look for an easier solution.
7. Ask questions on the Scripting Guys forum, or on twitter / Facebook.

Recommendations for writers

It is beyond the scope in most cases to test down-level everything that one writes about – especially if one writes very often. If you know when a new feature that you intend to incorporate was introduced, by all means mention it in the code. You can even use #Requires to ensure that the script will not run on an earlier version of Windows PowerShell. But most of the time, it is simply best to mention what version of Windows PowerShell you are running on. Here are some recommendations:

1. Always tag, mention what version of Windows PowerShell you are running on when you write the code and the blog article.
2. Mention any down level features you are incorporating and when such features may have been introduced.
3. Always run your code with a minimal profile to avoid picking up a dependency from something set in your profile.
4. Always be aware of additional external software you may have installed that may be loading something into your environment that might not be standard.
5. If you are using some other ISE other than the Windows PowerShell ISE, make sure you note that in your writing as it could be introducing features, and would certainly impact your figures you show in your article.
6. Always date your article.
7. Always include some kind of writer profile / contact means so the reader knows who wrote the article.
8. Mention all assumptions, limitations that you know that are germane to your article / script.
9. Mention if the script requires elevated permissions.
10. Mention environment dependencies, OS limitations, and other things you know about your script / blog posting.

That is all I have for you today. Join me tomorrow when I’ll talk about more cool stuff.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. Also check out my Microsoft Operations Management Suite Blog. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy