Example of integrating help

[wekempf]

This pull request is not complete, but provides an example of how PowerShell help can be integrated directly in the code. I would volunteer to do all the work, but I'm unfamiliar with the code and frankly don't understand what some of the commands are ore why they are publicly exported? With this example merged you can do the following:

PS> help about_posh-git
PS> help Add-SshKey -Full

[wekempf]

Pardon my noobness. I'm very new to Git and GitHub, and I'm likely doing things wrong.

In any event, this is in response to #90 where you say you've outgrown readme files and the project needs a web page. There's nothing wrong with having a web page, but a PowerShell user would much prefer you to include PowerShell help. It's much easier to discover and use, and can give you all of the benefit of web page documentation while remaining contextual.

I've not provided full help. I can't, because I don't understand half or more of the commands exported by this module. Many of them seem to be helper commands you use internally, and really shouldn't be exported, but they are. So, what I've done is just provide a starting point. I've include an about topic, so you can see how that's done. The about_posh-git help topic covers everything that's on the web site (minus installation instructions, as that seems pointless here... you wouldn't be reading the topic unless you'd already installed posh-git). I've also added help to Add-SshKey to illustrate how you'd go about adding help for the commands.

I believe this would be of much more benefit than a web page or the wiki here.

[dahlbyk]

I'll see your Git/Hub noobness and raise you novice-level PowerShell. ;)

Seriously though, I've been hoping someone would turn up to give some guidance on how to make posh-git a better PowerShell citizen.

So PowerShell will automatically pick up about_posh-git.help.txt because it's in the same location as the module?

Many of them seem to be helper commands you use internally, and really shouldn't be exported, but they are.

As you correctly point out in #93 - I should really just hide my privates.

[wekempf]

Yeah, I'm novice-level PowerShell as well, but I'm trying to progress beyond that as quickly as I can :)

The built-in modules actually place the help topic files under a directory named for the locale (e.x. posh-git\en-US\about_posh-git.help.txt. If you're not localizing, though, it works fine to just put it in the module root. Since asking for this pull request, I've learned a few things about the format of the files, though. Not that there's any requirement, but you want to be as consistent with the built-in help topics as possible. I've written up the "rules" I've discovered here: http://digitaltapestry.net/blog/writing-powershell-about-help-topics. The pull request should be updated to follow the rules as much as possible. I'm willing to do this work if you'd like, but before tackling it I'd want you to "hide the privates" so I can write the best possible documentation with my limited knowledge of posh-git. Otherwise, don't actually pull this but use it as an example for your own efforts here.

I've also written a blog post about script module "best practices" (keeping in mind I'm also still a novice, but these practices have been accumulated from trustworthy sources), that you may also find helpful: http://digitaltapestry.net/blog/writing-powershell-about-help-topics

[dahlbyk]

/cc @shiftkey

[rkeithhill]

An about topic was added back in May but we haven't shipped an update since then. I have merged your Add-SshKey help into GitUtils.ps1.