Documentation improvements per Suggested doc improvements #409

Author: jstetson10

docs/Configuration.md

@@ -2,107 +2,102 @@
 layout: default
 title: Configuration
 permalink: /configuration/
-nav_order: 5
+nav_order: 3
 ---
 # Configuration
 
-The settings that define an InterSystems IRIS server and the connection to the server are crucial to the functioning of VS Code in developing in ObjectScript.
+VS Code settings enable you to customize various aspects of its function. The InterSystems-provided extensions enable you to define InterSystems IRIS servers and the connections to those servers.
 
-## Configuring a Server
+## Settings
+
+Many available settings are general to VS Code, and you can learn about them in the [Visual Studio Code Documentation](https://code.visualstudio.com/docs). The InterSystems Server Manager and InterSystems ObjectScript extensions supply specific settings used to configure VS Code for ObjectScript development.
+There are several levels on which settings are stored and used:
+
+- **User** - User settings are stored in a file location specific to you and apply globally to any instance of VS Code or any VS Code workspace that you open.
+- **Workspace** - Workspace settings are stored in a file inside the workspace and apply to anyone who opens the workspace.
+- **Folder** - If more than one folder is present in the workspace, you can select the folder where the settings file is stored by selecting from the Folder drop down list.
 
-First, configure one or more servers. Open the settings editor by selecting **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) from the menu. Select the **User** or **Workspace** settings level by selecting it at the top of the settings window. For example, the following screen shot shows Workspace selected:
+For example, the following screen shot shows Workspace selected:
 
 ![Workspace selected.](../assets/images/ClickWorkspace.png "workspace selected")
 
-Find Extensions in the list in the left pane of the editor window, click to open, then select InterSystems Server Manager from the list to find the correct place in the settings UI. The following screen shot shows InterSystems Server Manager selected:
+See the VS Code documentation section [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings).
 
-![Select server manager.](../assets/images/ServerManagerSelect.png "select server manager")
+## Configuring a Server
 
-And this screen shot shows Server Manager area of the edit pane:
+First, configure one or more servers. Select **View > Command Palette > InterSystems Server Manager: Store Password in Keychain**. This command lets you define a new server, as well as storing a password. Click the plus sign in the upper right corner of the dialog, as shown:
 
-![Server manager settings.](../assets/images/ServerManagerSettings.png "server manager settings")
+![Define New Server.](../assets/images/new-server.png "define new server")
 
-You need to edit the server configuration in the settings.json file, so your only option is to click *Edit in settings.json*. 
+Provide the following values when prompted:
 
-To configure a server, enter code something like this:
+- **Name of new server definition** - an arbitrary name to identify this server
+- **Hostname or IP address of web server** - the host for this server
+- **Port of web server** - the WebServer port number for this server
+- **Username** - the username to use in logging in to this server.
+- **Confirm connection type** - the protocol used for connections, possible values are **http** and **https**.
 
-```js
-"intersystems.servers": {	
-	"test": {
-		"webServer": {
-			"scheme": "http",
-			"host": "localhost",
-			"port": 52774,
-		},
-	"username": "_SYSTEM",
-	},
-},
-```
+Once you have entered these values, the server definition is stored in your user settings. At that point another prompt appears, asking for a password to store in the system Keychain. Enter the password for the username supplied earlier to complete the process.
+
+## Editing a Server Configuration
 
-The components of this server definition are:
+If you need to modify a server configuration select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) from the menu. Select the **User** settings level. Find **Extensions** in the list in the left pane of the editor window, click to open, then select **InterSystems Server Manager** from the list to find the **InterSystems Server Manager** area of the edit pane, as illustrated in the following screen shot:
 
-- **test** - an arbitrary name to identify this server
-- **webServer** - The collection of properties that define the web server.
-- **scheme** - The protocol used for connections.
+![Server manager settings.](../assets/images/ServerManagerSettings.png "server manager settings")
+
+Click *Edit in settings.json*.
+
+The server configuration in *settings.json* looks similar to the following, with the values you entered when you configured the server:
+
+```json
+{
+    "intersystems.servers": {
+        "iris-1": {
+            "webServer": {
+                "scheme": "http",
+                "host": "localhost",
+                "port": 52773
+            },
+            "username": "_SYSTEM"
+        }
+    }
+}
+```
+The components of the server definition are as follows:
+
+- **iris-1** - An arbitrary name to identify this server
+- **webServer** - The collection of properties that define the web server
+- **scheme** - The protocol used for connections
 - **host** - the host for this server
 - **port** - the WebServer port number for this server
-- **username** - the username to use in logging in to this server.
+- **username** - the username to use in logging in to this server
 - **password** - password for the specified username. Entering the password in this file is acceptable only in limited situations with very low need for security. 
 
-If you do not add a password to the server definition, anyone using the server needs to supply the password. Or, you can store the password securely in the system Keychain. The InterSystems Server Manager adds the following commands for managing stored passwords to the Command Palette:
+If you do not store the password securely in the system Keychain or add it to the server definition, anyone using the server needs to supply the password. The InterSystems Server Manager provides the following commands for managing stored passwords in the Command Palette:
 
-- **InterSystems Server Manager: Clear Password from Keychain** - remove password for selected server
-- **InterSystems Server Manager: Store Password in Keychain** - select a server and enter a password
-- **InterSystems Server Manager: Test Server Selection**
-- **InterSystems Server Manager: Test Server Selection (flush cached credentials)**
-- **InterSystems Server Manager: Test Server Selection with Details**
+- **InterSystems Server Manager: Clear Password from Keychain** - remove the password for a selected server
+- **InterSystems Server Manager: Store Password in Keychain** - select a server or create a new one and enter a password
 
 ## Configuring a Server Connection
 
-Select InterSystems ObjectScript from the settings editor extensions list. You need to edit the server configuration in the settings.json file, so your click *Edit in settings.json* under the heading **Objectscript: conn**. 
+Open the folder where you want client-side files to be located. Select the **ObjectScript Explorer** button which has been added to the Activity Bar. Select the **Choose Server and Namespace** button. This action opens a dialog that lets you select a server, or create a new one. Once you have selected a server and namespace, connection configuration is complete.
+
+## Editing a Server Connection
+
+If you need to modify a server connection select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) from the menu. Select the **Workspace** settings level. Search for **objectscript: conn**, and click on *Edit in settings.json*.
 
-You should enter code something like this:
+The connection configuration looks like this:
 
-```js
+```json
 "objectscript.conn": {
 	"ns": "USER",
-	"server": "tst",
+	"server": "iris-1",
     "active": true,
 },
 ```
-The components of this server definition are:
+
+The components of this configuration are:
 
 - **ns** - namespace to use on the server
 - **server** - server name as specified in the server configuration
-- **active** - specifies whether the connection is active.
-
-## Configuring Export from Server
-
-Select InterSystems ObjectScript from the settings editor extensions list. Find the section labeled **Objectscript: export**.  You can edit many of the export settings in the settings editor. For others you need to edit the settings.json file.
-
-You export configuration looks something like this:
-
-```js
-"objectscript.export": {	
-    "folder": "",
-    "addCategory": true,
-    "atelier": true,
-    "generated": false,
-    "filter": "",
-    "category": "*",
-    "noStorage": false,
-    "dontExportIfNoChanges": false,
-    "maxConcurrentConnections": 0
-},
-```
-The components of this export definition are: 
-
-- **folder** - Folder for source code.
-- **addCategory** - Add a category folder to the export path.
-- **atelier** - Export source code as Atelier does, with packages placed in subfolders.
-- **generated** - Export generated source code files.
-- **filter** - An SQL filter that can be used to match the names.
-- **category** - Specifies a category of source code to export: CLS = classes; RTN = routines; CSP = csp files; OTH = other. The default is *, export everything.
-- **noStorage** - Strip the storage XML on export. This is useful for multiple systems.
-- **dontExportIfNoChanges** - Don't update the local file if the content is identical to what is on the server.
-- **maxConcurrentConnections** - The maximum number of export connections. (0 = Unlimited)
+- **active** - specifies whether the connection is active.

docs/Installation.md

@@ -29,6 +29,6 @@ Type `intersystems` in the search field to find these extensions in the Marketpl
 
 ![Search in Marketplace.](../assets/images/marketplace.png "search in marketplace")
 
-For each of the listed extensions, click the extension, then click **install**. Note that the InterSystems ObjectScript extension adds an ObjectScript button to the Activity Bar:
+For the ObjectScript and Server Manager extensions, click the **install** button. Note that the InterSystems ObjectScript extension supplies an ObjectScript button which appears in the Activity Bar when a workspace or folder is open:
 
 ![ObjectScript button.](../assets/images/objectscript.png "objectscript button")

docs/RunDebug.md

@@ -2,7 +2,7 @@
 layout: default
 title: Running and Debugging
 permalink: /rundebug/
-nav_order: 6
+nav_order: 4
 ---
 # Running and Debugging
 

docs/ServerSide.md

@@ -2,17 +2,28 @@
 layout: default
 title: Server-side Editing
 permalink: /serverside/
-nav_order: 7
+nav_order: 5
 ---
-# Server-side Editing
+# VS Code Workspaces
+
+To work with VS Code, you need to open a workspace. A VS Code workspace is usually just the root folder of your project. Workspace settings as well as debugging and task configurations are stored in the root folder in a folder called .vscode.
+
+If you need to have more than one root folder in a VS Code workspace, use a feature called multi-root workspaces. See [Multi-root Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) in the VS Code documentation.
+
+A multi root workspace contains a \*.code-workspace file. The file can have any name followed by *.code-workspace*, for example `test.code-workspace`. The .code-workspace file stores information about what folders are in the workspace. Other settings that would otherwise be stored in the settings.json or launch.json file can be stored in the .code-workspace file. You can optionally have a workspace file even if you are not using the multi-root feature.
+
+To edit a *.code-workspace* file in VS Code using the **InterSystems ObjectScript** extension, select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) and select the Workspace option. When you click **Edit in settings.json**, VS Code opens the *.code-workspace* file for that workspace.
+
+The **InterSystems ObjectScript** extension uses the multi-root workspaces feature to support ObjectScript development on the InterSystems server.
+
+# Server-side Source Control
 
 You can configure the InterSystems ObjectScript extension to edit code directly on the server, using the [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) VS Code feature. This type of configuration is useful in cases where source code is stored in a Source Code Management (SCM) product interfaced to the server. For example you might already be using the Source Control menu in InterSystems Studio or Portal, implemented by a source control class that extends `%Studio.SourceControl.Base`. 
 
 First configure the `intersystems.servers` entry for your server, as described in [Configuration](../configuration).
 
 Next create a workspace for editing code direct on the server:
 
-=======
 1. Open VS Code. If a folder or workspace is already open, close it, for example by pressing <kbd>Ctrl/Cmd</kbd>+<kbd>K</kbd>, releasing that keypair, then pressing <kbd>F</kbd>.
 
 2. Open the Explorer view (<kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>E</kbd>) if it is not already visible.

docs/Settings.md

@@ -7,8 +7,6 @@ nav_exclude: true
 
 * [Introduction](./introduction)
 * [Installation](./installation)
-* [Workspace](./workspace)
-* [Settings](./settings)
 * [Configuration](./configuration)
 * [Running and Debugging](./rundebug)
 * [Server-side Editing](./serverside)