Learn about Windows PowerShell
Summary: Read these tips to help you write outstanding Windows PowerShell Help.
Microsoft Scripting Guy, Ed Wilson, is here. Our guest blogger today is June Blender. June is a writer for the Windows Azure AD SDK. She is also a frequent contributor to the Hey Scripting Guy! blog, and for PowerShell.org.
Examples are the most important element of Windows PowerShell cmdlet Help. Many users skip the narrative and read only the examples for guidance about using the cmdlet. As such, it's important to include as much information in the examples as possible. Use the following guidelines when composing your examples:
This command uses the CSDVersion property of Win32_OperatingSystem to verify that Service Pack 1 is installed:
PS C:\> (Get-CimInstance Win32_OperatingSystem).CSDVersion
Service Pack 1
CSDVersion is one of many properties of the Win32_OperatingSystem object that Get-CimInstance returns. To see all of the properties in a list, pipe the object to the Format-List cmdlet, for example:
Get-CimInstance Win32_OperatingSystem | Format-List –Properties *
Example 4 Get-Help –ShowWindow This command displays the Help topic in a separate window. The ShowWindow parameter was introduced in Windows PowerShell 3.0.
Always use general good-writing practices in your examples. Use active voice in example descriptions, avoid fancy verbs (use "get" and "change," not "retrieve" and "modify"), and edit for clarity.
Help really is a community effort. If you have questions about examples, or you'd like to improve an example in your Help topics, send the Windows PowerShell help team an email at Write-Help@Microsoft.com.
Thanks, June! Join me tomorrow when I have a guest blogger who will talk about Windows PowerShell and security.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at firstname.lastname@example.org, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy
Proper help is very important indeed. What's the use of creating something great if people can't or don't know how to use it properly. I especially like:
•The best examples are realistic. They use the cmdlet and its parameters to solve real-world problems.
If this is in place, then it makes users to get help easily
(Get-Help Get-Date).Examples - This includes short note description - Very UseFul