In my last post one of the best practices I mentioned was including about help topic documentation in your modules. What wasn’t covered there was what your “about_ModuleName.help.txt” file should contain. There doesn’t seem to be much documentation about this anywhere. Basically, this file can contain anything, but you’ll generally want it be similar to other about help topic entries. Luckily, there are quite a few included with PowerShell for us to learn from.
gci $PSHome -inc *.help.txt -rec
This command will show you all of the about help topic files included with PowerShell. By inspecting them we can come up with a few rules to follow when writing our own.
Each about help topic should include the following sections: TOPIC, SHORT DESCRIPTION, LONG DESCRIPTION and SEE ALSO. Contents of these sections should be indented by 4 characters. Subsections can be included, with their header indented by 2 characters and their contents indented by 6 characters. Lines should not exceed 80 characters in length. Paragraphs should be delimited by blank lines. The first paragraph in the main sections should not have any blank lines between it and the header, while subsections should have a single blank line between the header and the first paragraph. Main section headers should be in all capitals, while subsection headers should be title-cased.
TOPIC should contain a single line indicating the topic the user used to display this help (e.x. “about_ModuleName”).
SHORT DESCRIPTION should contain a single paragraph (and no subsections) summarizing the topic.
LONG DESCRIPTION should contain the full description of the topic and can contain subsections.
SEE ALSO should contain “links” to other information sources, one per line. Usually this will be other names that can be supplied to Get-Help, but you can also include URLs to online information or other sources.
Here’s an example format template:
TOPIC about_TopicTitle SHORT DESCRIPTION One paragraph description of the topic. LONG DESCRIPTION Longer descrition of the topic. This can contain multiple paragrahs and subsections. Be sure to manually wrap within 80 columns. Some Subheading Indent subsections by 6 characters. SEE ALSO http://example.com about_SomeOtherTopic Get-Foo
I'm sure there's other "rules" I've missed, but this is a good starting place.