Chapter 29. Writing help
This chapter covers
- Writing comment-based help
- Writing About content help
- Writing XML-based help
As you develop your own scripts and functions, or even if you dive into .NET Framework programming and create your own binary cmdlets, you’ll doubtless want to include help with them. PowerShell’s help system is a crucial feature for shell users, giving them the ability to discover, learn, and use commands. Without help, your functions and cmdlets become essentially invisible, unlearnable, and unusable. Fortunately, PowerShell makes it relatively easy to write your own help.
One thing we’ve seen in recent Scripting Games is that many people try to develop their own way of delivering help. This is a bad idea because it takes time and effort that’s better spent in developing additional functionality for your organization. Use comment-based help or XML-based help as described in this chapter to provide the information your users need while minimizing the work you must do.
The easiest way to provide help is using the shell’s comment-based help feature (read about_comment_based_help in the shell for full details). This feature scans scripts, functions, and modules for specially formatted block comments, which use certain keywords to define the common sections of a help file: synopsis, description, parameters, examples, and so forth. Here’s an example of a comment block: