Wednesday, February 04, 2015

Creating Help Files for PowerShell – Sapien PowerShell Help Writer

In PowerShell you can get Cmdlet/Script/Function help in a couple of ways. First, you can use Comment Based Help – just put in a few carefully scripted comments and the Get-Help engine can provide help. This is fine for Advanced Functions, but if you want anything richer, including real cmdlet help text, you need to use  MAML (Microsoft Assistance Mark-up Language. MAML is a variant of XML, and in my experience is almost impossible for normal people to write using just Notepad (or other text editor).

There have been a few GUI-based tools over the years that have purported to do this – but in my exper5inence none of them have ever worked. I suspect Microsoft has some internal tools, but these have not been released outside Microsoft. Well – Until now that is!!

In her blog article entitled Introducing PowerShell Help Writer 2015, June Blender announces a new tool, PowerShell Help Writer (PHW). PHW is a new tool, developed by Sapien. This stool does a variety of things including being a fully feature Help tool that makes it easy to write and manage complete and more complex Help topics.

June's blog post has some more detail on the product, and you can find out even more by going over to Sapiens's web site for PHW: http://www.sapien.com/software/powershell_helpwriter. Sadly, the tool is not free (it costs US$49.00). It's disappointing at one level – at that price, casual scripter's, small business, etc are unlikely to pay for the product. I continue to believe this tool, or something like it, should be produced by Microsoft and as part of PowerShell or PowerShell ISE.

Still, if you are writing enterprise cmdlets, or commercial products, then this tool is almost a given. Unless you are one of the very, very few who can write MAML!

del.icio.us Tags: ,,,

2 comments:

Roman Kuzmin said...

There is a free non-GUI tool -- https://github.com/nightroman/Helps

It generates / uses help scripts written in PowerShell itself. It is unusual perhaps but simple and yet powerful. Localized help is not a problem, too.

SAPIEN Technologies said...

Thanks, Thomas. I really hope that people try PowerShell Help Studio and send us feedback. The current version is really a 1.0 and we'll be using feedback to help us decide which features to add next (provider help, Updatable Help, online help, etc.)

We have a 45-day free trial, so everyone can get to know PowerShell Help Writer without making any commitment. After that, it's just $49, which costs about as much as pizza lunch for a small IT team, and it lasts much longer.

And, the $49 gets you all product updates and upgrades, including major product releases for a full year. At the end of the year, you can renew, or continue to use that year's latest version indefinitely.

If folks have questions, they can come directly to me: juneb at sapien dot com.

Thanks!
June Blender
Technical Evangelist
SAPIEN Technologies, Inc.