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 write-help@microsoft.com. 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!
No comments:
Post a Comment