Updated Virtual Workspaces (markdown)

Virtual-Workspaces.md

@@ -4,17 +4,15 @@ We have recently announced the [Remote Repository feature](https://code.visualst
 
 While developing and testing the feature, we have observed that not all extensions work well with it. What's special about Remote Repositories is that they open VSCode on a folder or workspace that is located on a virtual file system. We call this a __virtual workspace__. 
 
-When a virtual workspace is open in a VS Code window, this is shown by a label in the remote indicator in the lower left corner, similar to remote windows. In that window, we disable all extension that that signal that they don't support virtual workspaces.
+When a virtual workspace is open in a VS Code window, this is shown by a label in the remote indicator in the lower left corner, similar to remote windows. In that window, we disable all extension that signal that they don't support virtual workspaces.
 
 We want to make sure as many extensions as possible work with virtual resources. We aim for a good user experience not just with the __Remote Repository__ feature, but also all other features leveraging virtual resources, from connecting to ftp-servers to working with cloud resources. Features that depend on resources being available on disk should not cause error dialogs.
 
-This guide is for extension authors and documents how an extension can fully support a virtual workspace or, if it can not, how it can signal that it should be disabled when a virtual workspace is opened.
-
 ## Is my extension affected?
 
 When a extension has no code but is a pure theme, keybinding, snippets, grammar extension, then it can run in a virtual workspace and no adoption is necessary.
 
-Extension with code, that means extensions that define a 'main' entry point, require inspection and, possibly, adoption.
+Extension with code, that means extensions that define a `main` entry point, require inspection and, possibly, adoption.
 
 ## Run your extension against a virtual workspace
 
@@ -22,9 +20,9 @@ Run the **Open Remote Repository...** command from the Command Palette. **Notice
 
 This opens a VSCode window for a virtual workspace where all resources are virtual. 
 
-## Verify that the code is ready for virtual resources
+## Review that the code is ready for virtual resources
 
-The API support for virtual file system has been around for quite a while already. You can check out the [file system provider API](https://github.com/microsoft/vscode/blob/dc8bd9cd7e5231745549ac6218266c63271f48cd/src/vs/vscode.d.ts#L7038), if you are interested. A file system provider is registered for a new URI scheme (e.g. `vscode-vfs`) and resources on that file system will be represented by URIs using that schema (e.g. `vscode-vfs://github/microsoft/vscode`)
+The API support for virtual file system has already been around for quite a while. You can check out the [file system provider API](https://github.com/microsoft/vscode/blob/dc8bd9cd7e5231745549ac6218266c63271f48cd/src/vs/vscode.d.ts#L7038), if you are interested. A file system provider is registered for a new URI scheme (e.g. `vscode-vfs`) and resources on that file system will be represented by URIs using that schema (e.g. `vscode-vfs://github/microsoft/vscode`)
 
 Check how your extension deals with URIs it gets from the VSCode APIs:
 
@@ -33,11 +31,11 @@ Check how your extension deals with URIs it gets from the VSCode APIs:
 - Check for third party components that depend on a `fs` access (e.g. a language server or a node module)
 - If you run executables and tasks from commands, check whether these commands make sense in a virtual workspace window or whether they should be disabled.
 
-## Adopt your extension to work with virtual workspaces
+## Signal whether your extension can handle virtual workspaces
 
-We have introduced a new `capabilities` property in`package.json`.
+There's a new `capabilities` property in `package.json`, and `virtualWorkspaces` is used  to signal whether an extension works with virtual workspace, or not.
 
-The `virtualWorkspaces` capability property signals whether the extension works with virtual workspace, or not. The example below declares that an extension does not support virtual workspaces and should not be activated by VS Code in this setup.
+The example below declares that an extension does not support virtual workspaces and should not be activated by VS Code in this setup.
 ```json
 {
   "capabilities": {
@@ -46,12 +44,12 @@ The `virtualWorkspaces` capability property signals whether the extension works
 }
 ```
 
-When an extension can partially work with virtual workspaces, then it should define `"virtualWorkspaces": true` but it should disable the features that are not supported in a virtual workspace. 
+When an extension works with virtual workspaces, then it should define `"virtualWorkspaces": true`. If it partially works, it should do the same, but it should disable the features that are not supported in a virtual workspace. 
 
 Until extensions have adopted the new capability, we came up with an internal list of extensions that we think should be disabled in virtual workspaces. 
 The list can be found [here](https://github.com/microsoft/vscode/issues/122836). 
 
-But of course, extension authors are in better position to make this decision. Once a extension has adopted the capability, we will remove the extension from the list.
+Of course, extension authors are in better position to make this decision. Once a extension has adopted the capability, we will remove the extension from the list.
 
 ## Disable functionality when a virtual workspace is opened
 
@@ -60,7 +58,7 @@ But of course, extension authors are in better position to make this decision. O
 The availability of commands and views and many other contributions can be controlled through context keys in [`when` clauses](https://code.visualstudio.com/api/references/when-clause-contexts).
 
 The `virtualWorkspace` context key is set when all workspace folders are located on virtual file systems. The example below shows the command `npm.publish` in the command palette only when not in a virtual workspace:
-```
+```json
 {
     "menus": {
       "commandPalette": [
@@ -68,13 +66,14 @@ The `virtualWorkspace` context key is set when all workspace folders are located
           "command": "npm.publish",
           "when": "!virtualWorkspace"
         }
+      ]
     }
 }
 ```
 
-The 'resourceScheme` context key is set to the URI scheme of the currently selected element in the explorer or the element open in the editor. 
+The `resourceScheme` context key is set to the URI scheme of the currently selected element in the explorer or the element open in the editor. 
 In this example the `npm.runSelectedScript` command is only in the editor context menu if the underlying resource is on the local disk.
-```
+```json
 {
     "menus": {
       "editor/context": [
@@ -91,7 +90,7 @@ In this example the `npm.runSelectedScript` command is only in the editor contex
 
 To check in code whether the current workspace consists of non-`file` schemes and is virtual you can use
 
-```
+```ts
 const isVirtualWorkspace = workspace.workspaceFolders && workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');
 ```
 
@@ -99,7 +98,7 @@ const isVirtualWorkspace = workspace.workspaceFolders && workspace.workspaceFold
 
 When registering a provider for a language feature (e.g. completions, hovers, code actions..) make sure to specify the schemes the provider supports:
 
-```
+```ts
 return vscode.languages.registerCompletionItemProvider({ language: 'typescript', scheme: 'file' }, {
 	provideCompletionItems(document, position, token) {
 		// ...
@@ -107,6 +106,6 @@ return vscode.languages.registerCompletionItemProvider({ language: 'typescript',
 });
 ```
 
-## More Information and comments
+## More information and feedback
 
 Please comment in the [Virtual Workspaces Tracking Issue](https://github.com/microsoft/vscode/issues/123115) if you have questions and suggestions.