CmdLet Help

[lipkau]

Proposal

I would propose for use to use platyps in our modules.

What is PlatyPs

PlatyPS allows use to export the Comment Based Help of the functions into a MarkDown file (per function) and to convert these .md files into real external help files.

How would it work

• We export all current help into markdown files
• We remove all Comment Based Help from the files (Reason is listed in Cons)
• We edit the resulting .md files to our needs
• The CI/CD (Appveyor) would build these into external help files (.xml) and place them in the module

This would also work for the about_<moduleName> file/help

Pros

• Better formatted help --> Examples could have more than 1 <code> line
• Help of each function would be accessible in the GitHub repo (with nice formatting)
• Module must not have a new release for only changes in the Help (although it can)
• Help could be deployed with Update-Help
• .md files could be shown (and edited) on our wordpress homepage

Cons

• Help would no longer be in the same file as the function. Vors explained why:

hm, good question. I actually not sure what help engine does.
once you converted help to markdown, you would not be able to keep the description strings in sync: the metadata would be from the source code, but strings would be from the markdown.
hence, it will slowly but surely got out of sync between the two sources.
so I’d suggest to remove the comment based help once you converted help to markdown

[lipkau]

@AtlassianPS/maintainers ,
What do you think? Please comment

[replicaJunction]

I'm strongly in favor of this. I just started using platyPS for some internal company modules a few days ago, and it's great! Quite simple to use and maintain the help docs. Having the help in a separate file in the repo isn't a problem as long as the CI job builds and deploys the help file properly.

Markdown isn't as scary as ReStructured Text (what I initially chose for the ReadTheDocs repo for JiraPS), so we might get more contributions to help (especially examples). It's also a lot easier to double-dip with markdown. GitHub wiki and ReadTheDocs both support markdown, though I haven't tested how either one works with platyPS's unique flavor, so we could experiment with some interactions there to have a friendly online help system as well.

[brianbunke]

Con: It involves facing the sad reality that the internal PS help engine may never be improved
Con: Extra work 😞

Pro: It's pretty excellent once it's up and running

I'm not a GitHub wiki fan, but using GitHub Pages or ReadTheDocs would be a suitable host for these files.

[lipkau]

OK. So we agree that it's a good idea.
I will create the task issues for the modules and start on this.

But we still need to discuss how to continue with this...
I am real fan of having the files in /docs (and not a branch)
And have an AtlassianPS/AtlassianPS-Docs (or similar) with the common stuff, such as how to contribute