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!
0 Comments