Vscode-powershell: Create a documentation page for the settings

[noopman]

It is difficult to know what settings are available in VS Code PowerShell. This should be documented!

'As a script author I want fun small parts of my scrip using F8 and then continue to immediately author.
Turns out there is a VS Code PS setting for this called "powershell.integratedConsole.focusConsoleOnExecute". If I don't know that this is I will not be able to set it. If I'm not able to set it I will have to live with having an interrupted flow from either performing an odd piece of keyboard gymnastics to get back to my script or by moving my hand to the mouse.

This is just one simple example of settings that should be documented. I'd love to know what other gold I can configure!

Proposed technical implementation details (optional)

Create a page for the documentation of all the great settings in VS Code PS! If you have that we can all link to it and you can point to it rather than explaining the same things over and over again to people who ask! This will increase the usefulness of VS Code PS for ordinary users!

[TylerLeonhardt]

Thanks @noopman!

[rkeithhill]

Having more docs is always good but … if you use various different extensions you will likely run into this issue with them as well. One way to "discover" settings right now is to select File | Preferences | Settings. In the search box type in powershell. and you will see all the PowerShell extension settings. You will see the documentation for each setting as a comment e.g.:

You can do the same thing for other extensions you have installed.

[Halkcyon]

@rkeithhill VSCode also shows extension settings by tabs in that pane so you can collapse everything but "PowerShell Configuration" (also a new WIP graphical settings configuration)

[yobyot]

+1

IMHO, the doc for this extension is execrable. It's in multiple places, including release notes as opposed to documented features, incomplete and generally impossible to use.

I realize the team is working hard on functionality. But what use is that if nobody can find in a single, coordinated place, what the extension is capable of?

I was moved to add my two cents to this issue by the futile search for a complete discussion of extension-provided pwsh snippets. This project is becoming a poster child for the old adage that dev teams delay doc until it's too late. This extension is by no means the only project in this state -- it seems like all of Microsoft is a consumable-doc-free-zone. But for development tools, it's inexcusable.

[rjmholt]

We're spread a bit thin at the moment, and admittedly documentation tends to get pushed down the queue. I'm optimistic that we've begun to reverse the trend recently.

We've relied so far on the self-documentation of settings in the case here, and have tried to invest in the most needed documents, such as:

• The VSCode PowerShell doc
• Microsoft docs' PowerShell VSCode extension entry
• The ISE experience doc
• The CHANGELOG (which is generated from commits, meaning it should capture all changes, provided commit messages are descriptive)

As the developers though, we have quite a different view up at the coalface to consumers of the software downstream, and can always use help identifying and addressing blind spots in documentation.

@yobyot Is there anything specifically you feel we need to be addressing in terms of documentation that isn't addressed in one of the above documents? Or maybe those documents aren't visible enough? Is there any area of the extension you feel is not well documented, or any features you know about (wholly or partially) that you would like to see more documentation on?

As a final note, I think it's worth mentioning that user-contributed documentation tends to be better, since the assumed knowledge level is likely to be more accurate. It's very easy to contribute documentation, just by opening a PR to edit or add a markdown file (worst case scenario, we can move it to Microsoft Docs) -- in fact I think GitHub's current interface allows you to write a new doc without even leaving the browser.

[yobyot]

I want to repeat that I totally respect the fact that the dev team is "at the coalface." In addition, I very much appreciate the level of interaction the PowerShell team has with end users here on GitHub. I'm an "old man" in tech -- and I've _never_ before been able to interact directly with the team at the level of fidelity you guys permit here on GitHub.

That said, and you guys know I love you, @rjmholt 's response makes my point: these individual pieces of data, in different places and styles, each with a different focus are _not_ product documentation. They are more like notes. They leave the user confused about where to go for comprehensive information.

What's needed is a single, authoritative, complete and indexed document containing at least an introduction, concepts and capabilities and an alphabetical listing of every option. This belongs on docs.microsoft.com.

Here's a challenge: where is the doc describing in detail createTemporaryIntegratedConsole for the debugger?

I think the challenge is that devs assume too much -- as in this case, they assume that users would know why and how to use a temp console for debugging. But they won't -- and that's why doc is so important. Features need to be explained, detailed as to their purpose and intent as well as simply described