Review snippets guide / sample

[octref]

• https://vscode-ext-docs.azurewebsites.net/api/language-extensions/snippet-guide
• https://github.com/Microsoft/vscode-extension-samples/tree/master/snippet-sample

The source of doc is at https://github.com/Microsoft/vscode-docs/blob/ext-docs/api/language-extensions/snippet-guide.md

Please review this guide / sample combo. Edit as you fit, and add things you think are missing.

[jrieken]

I have removed the advertisement because that doesn't belong in a technical guide. Then I think that the whole guide as zero meat and it took me a really long time understand what the goal is. Makes me question what the guides are about? Is the goal to explain every single contribution point? How does this compare to Extension Guides?

[octref]

@jrieken I was thinking maybe we should add pointers to successful usages of a pattern. For example, TreeView doc could say: "GitLens and GitHub PR extensions are two extensions that use this extension API". Are you opposed to including any such pointers in the API doc?

I agree this guide currently does not have much meat. It's

1. For the sake of completeness in Language Extensions section
2. For letting user know "The contributes.snippets Contribution Point allows you to bundle snippets into an extension for sharing." I think new users do not realize they could bundle & share extensions.

Is the goal to explain every single contribution point?

Yes, these three sections take care of grammars, languages and snippets.

How does this compare to Extension Guides?

Languages support is a large area of our API so I extracted it out into its own section. Otherwise I end up with a gigantic Extension Guides section.

[jrieken]

"GitLens and GitHub PR extensions are two extensions that use this extension API". Are you opposed to including any such pointers in the API doc?

Maybe as appendix for further reading, surely not atop as the first thing to see and I am also not a fan of the tiles as they grab too much attention.

[octref]

Sounds good. I'll close this one then.

I did point to other extensions in the Extending Workbench topic. Feel free to open new issues if you don't like that either: https://vscode-ext-docs.azurewebsites.net/api/extension-capabilities/extending-workbench