I thought I’d mentioned this last time (tap tap, this thing on?), but maybe not: don’t format the output of your functions. The minute a function includes Format-*, you’ve trapped me into on-screen display, a text file or piece of paper modeled after the on-screen display, or not a lot of other choices. If I want formatting, I’ll pipe your function to my own Format-* command of choice. But if I want CSV, or HTML, or XML, I’d like that option. Thanks.
This is not a favorite technique of mine:
I continue to be amused by folks’ reactions to the Games this year.
There’s been some buzz on Twitter this morning from folks who feel some of their comments - and the corresponding low scores - aren’t warranted. In a couple of cases I’ve looked at, they’re right - their entries are being downrated for reasons that are actually not best practices; by following the best practices, these entries are getting lower scores.
This reinforces a point I keep trying to make: The Games aren’t about YOU. They’re about US. ****
Let me put it another way: if you’re getting comments from folks whose opinions are founded in a misunderstanding or misconception, that’s an opportunity to educate. Not to attack that commenter - which is why commenter names aren’t shown - but to educate the community in general. The community took the time to give you comments, and although some of them might be misguided, you can take the time to offer a productive counterpoint and perhaps lay some misunderstandings to rest.
That’s the point of the Games: to learn. Maybe not for you to learn, but maybe for you to help someone else learn. Or to put it another way, I haven’t received Microsoft’s MVP Award for ten years straight because I got a good “score” on something. I got it because I look for teachable moments and try to offer explanations. Being able to teach something shows that you really know it.
Think of your Games entries as a honeypot. If you can attract some folks who don’t quite get what you’re doing, then through the comments you’ll spot broad areas of educational opportunity, or what I call “teachable moments.” Seize on those and help bring the community as a whole to a higher level.
Does that mean the educational opportunity has to come at the cost of you getting a lower score? Yup. Will that score in any other way impact your life? Nope. It’s not going on your permanent record. Human Resources will never know. It won’t affect your salary, or your ability to choose which movie you will see this weekend (Iron Man 3, BTW). Thicken up that skin a little - every vote isn’t a personal attack on you. Every “unqualified” comment is not a stain upon your honor.
I really wish I could use some of the cooler interjections from Spartacus here, but none of that stuff is suitable for a professional environment :(.
In short: Cool yer jets. Take the opportunity to educate. Not on Twitter. Man, you guys with the tweets. You don’t have a blog, drop me an e-mail and I’ll give you authoring permissions right here on PowerShell.org. Help us, as a community, educate each other.
And hey, remember not ALL of your comments are non-constructive. Learn from the ones you can, tune out the rest. Like watching CNN. Ever notice how, on a slow news day, the talk about Atlanta’s traffic? Exactly.
We’re pleased to announce the winners for Event 1 of The Scripting Games 2013!
Winners: You can log into The Scripting Games Web site and go to your Profile page to see your prize. You will be given a prize redemption code and either a URL where you can redeem it, or an e-mail address of the prize provider (they will need the redemption code). All prizes must be claimed by the end of July 2013. I will list winners by username; if you used your e-mail address as your username, then a portion of that will be truncated for your privacy. Anyone can log in and check their Profile page to see if they’ve won a prize.
Aaron Hoover, one of our Summit attendees, was kind enough to record via webcam the sessions he attended - and he’s posted about 13 hours of video on YouTube for your viewing pleasure.
What I’d like to know from you, if you don’t mind dropping a comment below, is what you think of these. If we offered this KIND of recording in the future, would it be helpful? This is something we can do easily and is affordable from a technical perspective; there’s obviously a production quality compromise. We can do more… but it costs more, and someone’s going to have to pay for it. So… where do you sit on this kind of recording?
I haven’t received any negative feedback on idea to blog about “how would I do it” (what you think about my approach is different topic) so I decided to continue. Again: because I don’t want to be influenced by your ideas and make my task as close to your work as possible I post it early, before I see any of cool techniques I haven’t thought of and you did, so that I can regret it later. You can find whole article on my blog. Enjoy, and please - if you see something silly, let me know. I really do appreciate negative feedback!
Event 2 has closed for submissions and will open for voting later this evening. Good luck! And voters: remember that quality comments will vastly increase your chances of winning a prize!
The Scripting Games 2013 winners have not yet been announced, but for the 3rd year running, I’m in the lead for the “Learned Most from the Scripting Games” award. I’m making space for the prize on my bookshelf. Seriously, I play with PowerShell all the time and read lots of blogs, but nothing compares to looking at dozens of scripts and commands and seeing how people do things in the real world.
One of the practices I’ve noticed is use of the HelpMessage parameter attribute to document a parameter. It’s a real thing, but I didn’t know that anyone used it any more.
Here’s my help message about HelpMessage:
Don’t use it! Users can’t see it. It does no harm, but it has no value. Danger lurks in writing a HelpMessage instead of writing help that users can see. Write help that Get-Help gets, that is, XML help or comment-based help.
Here’s what I’m talking about. This code is valid. The language permits it. But it’s not useful. And I saw it in several of the advanced solutions.
What an amazing event. I’m now reading through each of the Advanced entries in a vain attempt to whittle the entries down to a short list. It’s an incredibly difficult task, which is testament to your skill and diligence. We are so lucky to have so many competent scripters in the community.
As I read through the comments on each script, I’ve noticed several that say:
“Help should be nested under the function to work properly.”
Au contraire! This is not true and I want to make sure that people who see this comment are not misled. The Windows PowerShell team designed comment-based help to be really flexible.
As I explained in about_Comment_Based_Help, you can put comment-based help for a function in one of three positions:
Right now, I’ve got the Scripting Games Web site built to only make comments visible to a entry’s author. Some of the comments have been a little snarky, and I don’t want to create an online argument forum.
I’m curious what folks think we should do as a next step.
I could, for example, make comments visible to everyone once voting has ended for an event (I don’t want to make comments visible while we’re still accepting comments, because it’ll run a big risk of creating a discussion, which isn’t the intent).
We do have a plan to dump all the entries into static files for long-term reference; I could insert entries’ comments at the end of each entry, in a PowerShell comment block.
Or, we could just leave comments visible to the entry’s author. That provides a learning experience for the author, although not for the public, and only until we purge the database for the next event.
Thoughts?
