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: PowerShell,MAML,Help,Sapien

PowerShell Help Information–how to report bugs/issues

As many readers of this blog know, I really value the excellent PowerShell Help information provided both in the box and on the web. With the thousands of cmdlets, providers and the large number of conceptual help topics (help about some aspect of PowerShell), there is a lot of document and a lot of documentation to co-ordinate. It’s a large task and, as is sadly inevitable when publishing such large amounts of information, errors and issues do sometimes creep in. I’ve been doing writing gigs for over 20 years, and it amazes me just how easy it is for simple errors to manifest themselves, despite rigorous checking. I used to get upset when I saw things like in my own writing, but these days, with documentation being electronic, I just look at errors as an opportunity to improve the help text.

I’ve been chatting to the PowerShell documentation team (a great bunch of folks, in case of ANY doubt!), and looking for good ways to ensure errors are resolved. If (when?) you find an error, the best thing to do is to send mail to [email protected]. Mail sent to that address goes straight to the writers responsible for PowerShell content. It doesn’t matter where the error is (so long as it’s on a Microsoft site!!!), if you see an error, please report it.

If you find an error, then report it using the Email address above. Ensure that Microsoft knows about the error and make sure that the error is one that can get fixed. The bottom line is that once published, there is a tacit assumption that it’s correct – thus if YOU don’t report it, it WILL NOT get fixed (unless, of course someone else reports it first!).

When you do report a bug, please give sufficient details to enable the team to find and resolve the issue. Reporting bugs with text like “the help text is broken” is not much help, so please report the specific location, the specific issue and where possible, provide corrected text. The easier you make it on the WSIX team, the faster the error can be corrected.

Please help to make the PowerShell help information even better!

Technorati Tags: PowerShell,help

PowerShell Version 3 – Help Soon Coming

As I blogged in March, PowerShell V3 comes with Updatable help. This is a fantastic new feature that allows for Microsoft, and any PowerShell module maker, to create updated help for the code in their modules. Thus errors can get fixed in the in-box help. The implementation Microsoft chose is not perfect – there is only minimal help ‘in the box’. You have to use Update-Help in order to get the help contents. I regard this as a bug, but Microsoft describe it as a feature. Irrespective, I do like this feature!

Now that Windows 8 is released, so is PowerShell V3. Sadly, not all the help text has been released. Given the thousands of new cmdlets that ship with V3 and Server 2012, this is not surprising. While it would have been nice to think that help text is a sufficiently important part of the product to complete before RTM – that wasn’t the way it was done. So in order to get help in PowerShell V3, you will need to continue to use Update-Help. Once all the help text is available, I’ll try to post again!

One artifact of this situation is that Update-Help generates a couple of errors. Today, if you try to update help, you may see the following error:

Update-Help : Failed to update Help for the module(s) 'CimCmdlets' with UI culture(s) {en-US} : For security reasons DTD is prohibited in this XML document. To enable DTD processing set the DtdProcessing property on XmlReaderSettings to Parse and pass the settings into XmlReader.Create method.
At line:1 char:1
+ Update-Help -force -verbose
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Update-Help], Exception
    + FullyQualifiedErrorId : HelpInfoXmlValidationFailure,Microsoft.PowerShell.Commands.UpdateHelpCommand

The problem here is that the CimCmdlets (and possibly other modules) point off to Microsoft’s web site where Update-Help is meant to be able to find the updated help for this module (or modules). Sadly, the pointer from the module points to a nonexistent page, which Microsoft helpfully points off to Bing. That’s great for most things, but Update-Help gets the Bing page, which it tries to read as XML which is not quite right.

This is sad, but PowerShell updated help is still a work in progress – and given the magnitude of the task, I suppose the PowerShell Team can be forgiven. I must say, a LOT of modules have been updated over the past few days, and I would expect all the help text to be complete well before General Availability of Windows 8 and Server 2012.

Bottom line: Updatable help rocks, but we need just a bit of patience till it’s all here!

 

Technorati Tags: PowerShell V3,PowerShell Updateable Help,Updable Help,Help