Template Documentation

[dansiegel]

The documentation needs a little cleanup particularly for Post Actions. For example in the "Runnable Project" Templates configuration section there is an example of what a template configuration could look like, and it includes some post actions. Several properties in the example do not meet the official schema which could really lead to some confusion.

Another point of confusion would be that the Post Actions in the sample don't actually make use of a real action in the Post Action Registry. It might also be good to link to the Post Action Registry from the description of the postAction.args. And you're looking at the Post Action Registry there's a lot of (TBD) or text that is larger than the view bounds. Ideally each one should have an example of use as you would see it in the post actions of your template.json

[sayedihashimi]

Hi @dansiegel thanks for the feedback. I just made a bunch of changes to runnable projects based on this.

The sample template.json file should now be schema compliant. I updated the content of the json file to use more realistic examples. That includes replacing the postActions with an actual postAction as you mentioned. I also added a link to Post Action Registry (PAR). I think the runnable projects page still needs a bit of work but better than before.

I think the only remaining item from your feedback is the PAR page itself. I see what you mean about the format.

[dansiegel]

@sayedihashimi that looks a lot better! One minor thing I might add is "$schema": "http://json.schemastore.org/template", I believe both VS and VS for Mac pick up the schema automatically, but VS Code and some other text editors don't pick it up without that defined, so it may not be bad to add the schema reference as well :)

As for the PAR page, I might add based on the feedback from @mlorbetske in #765

If the user passes --allow-scripts yes (this parameter defaults to prompt), then the prompts will not be displayed. This options should be visible in the template's help if it has script type post-actions. Generally though, we discourage the use of script type post actions as there's usually not a guarantee that the user has support for the command that's being run.

Reading the Wiki documentation on the Run Script post action, I would have no idea. As the template author, I wouldn't have a reason to think that a new symbol is available for my template when I didn't specify one in my template and there isn't anything documented about it.

[sayedihashimi]

@dansiegel FYI I've added $schema as you suggested. I also have updated the formatting of the PAR page. I'll discuss with @mlorbetske next week and see if we can get the Run Script section improved.

FYI the wiki pages are editable by anyone. If you see anything that can be improved and are up for it, then feel free to go for it.

[sayedihashimi]

I believe these docs have been added, closing.

[dansiegel]

@sayedihashimi I was actually just trying to add the Prism Quickstart Templates to the wiki but it's giving me a permission denied error.