doc updates

Author: Tim Etchells

CONTRIBUTING.md

@@ -1,44 +1,17 @@
 # Contributing
 
-Anyone can contribute to the Microclimate Tools for VSCode project, and we welcome your contributions!
+Anyone can contribute to the Microclimate Tools for VSCode project, and we welcome your contributions! [Visit us on Slack](https://slack-invite-ibm-cloud-tech.mybluemix.net/) if you have any questions.
 
 ## Raising issues
 
-Please raise any bug reports on the project's (put a link here). Be sure to search the list to see if your issue has already been raised.
+Please raise any bug reports [here](https://github.com/microclimate-dev2ops/microclimate-vscode-tools/issues). Be sure to search the list to see if your issue has already been raised, and visit our [troubleshooting page](https://microclimate-dev2ops.github.io/mdt-vsc-troubleshooting) too.
 
-A good bug report is one that make it easy for everyone to understand what you were trying to do and what went wrong. Provide as much context as possible so we can try to recreate the issue.
+A good bug report is one that make it easy for everyone to understand what you were trying to do and what went wrong. Provide as much context as possible so we can try to recreate the issue. Please upload your extension logs with your issue report; instructions for this are also available on the [troubleshooting page](https://microclimate-dev2ops.github.io/mdt-vsc-troubleshooting).
 
 ## Developer Certificate of Origin
 
-If you are contributing changes via a pull request, you must sign-off those changes against the *Developer Certificate of Origin*
+If you are contributing changes via a pull request, you must sign-off those changes against the [Developer Certificate of Origin](https://github.com/microclimate-dev2ops/microclimate-vscode-tools/blob/master/DCO1.1.txt).
 
-```
-Developer's Certificate of Origin 1.1
-
-       By making a contribution to this project, I certify that:
-
-       (a) The contribution was created in whole or in part by me and I
-           have the right to submit it under the open source license
-           indicated in the file; or
-
-       (b) The contribution is based upon previous work that, to the best
-           of my knowledge, is covered under an appropriate open source
-           license and I have the right under that license to submit that
-           work with modifications, whether created in whole or in part
-           by me, under the same open source license (unless I am
-           permitted to submit under a different license), as indicated
-           in the file; or
-
-       (c) The contribution was provided directly to me by some other
-           person who certified (a), (b) or (c) and I have not modified
-           it.
-
-       (d) I understand and agree that this project and the contribution
-           are public and that a record of the contribution (including all
-           personal information I submit with it, including my sign-off) is
-           maintained indefinitely and may be redistributed consistent with
-           this project or the open source license(s) involved.
-```
-To sign off and indicate you have agreed to the DCO, include a message in the following format on each commit in the pull request
+To indicate you have read and agreed to the DCO, use [`git commit --signoff`](https://git-scm.com/docs/git-commit#git-commit---signoff). It should result in something like the following at the bottom of your commit message:
 
 ```DCO 1.1 Signed-off-by: Random J Developer <[email protected]>```

DCO1.1.txt

@@ -0,0 +1,25 @@
+Developer's Certificate of Origin 1.1
+
+       By making a contribution to this project, I certify that:
+
+       (a) The contribution was created in whole or in part by me and I
+           have the right to submit it under the open source license
+           indicated in the file; or
+
+       (b) The contribution is based upon previous work that, to the best
+           of my knowledge, is covered under an appropriate open source
+           license and I have the right under that license to submit that
+           work with modifications, whether created in whole or in part
+           by me, under the same open source license (unless I am
+           permitted to submit under a different license), as indicated
+           in the file; or
+
+       (c) The contribution was provided directly to me by some other
+           person who certified (a), (b) or (c) and I have not modified
+           it.
+
+       (d) I understand and agree that this project and the contribution
+           are public and that a record of the contribution (including all
+           personal information I submit with it, including my sign-off) is
+           maintained indefinitely and may be redistributed consistent with
+           this project or the open source license(s) involved.

README.md

@@ -2,36 +2,37 @@
 
 [![Build Status](https://travis-ci.com/microclimate-dev2ops/microclimate-vscode-tools.svg?token=wpsJvyUkyhtfRa9prmMq&branch=master)](https://travis-ci.com/microclimate-dev2ops/microclimate-vscode-tools)
 
-This is the Git repository top-level README.
+- **[Marketplace](https://marketplace.visualstudio.com/VSCode)**
+- **[Documentation](https://microclimate-dev2ops.github.io/mdt-vsc-overview)**
+- **[Slack](https://slack-invite-ibm-cloud-tech.mybluemix.net/)**
+- **[Extension Readme](https://github.com/microclimate-dev2ops/microclimate-vscode-tools/blob/master/dev/README.md)**
 
-For the README packaged with this extension, see [the extension README fix this link](github.com)
+## How to install [(Documentation)](https://microclimate-dev2ops.github.io/mdt-vsc-getting-started)
 
-## How to install
-Need to update this
+1. Install [VSCode 1.27 or newer](https://code.visualstudio.com/download) and [local Microclimate 18.12 or newer](https://microclimate-dev2ops.github.io/installlocally).
+2. Install Microclimate Developer Tools for VSCode from the [VSCode Marketplace](https://marketplace.visualstudio.com/VSCode), or by searching for "Microclimate" in the [VSCode Extensions view](https://code.visualstudio.com/docs/editor/extension-gallery#_browse-for-extensions).
 
-## How to use
+For development builds, see the [releases page](https://github.com/microclimate-dev2ops/microclimate-vscode-tools/releases), and follow [these instructions](https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix) to install.
+
+## How to use [(Documentation)](https://microclimate-dev2ops.github.io/mdt-vsc-tutorial)
 - Open the Microclimate Projects view within the Explorer view group (`Ctrl/Cmd + Shift + E`),
     - Right-click to create a default local connection.
     - Right-click a project to see the actions available (see below)
-- Open the Command Pallete (`Ctrl/Cmd + Shift + P`) and type "Microclimate" to see the actions available
-
-Link to the documentation
+- Open the Command Palette (`Ctrl/Cmd + Shift + P`) and type "Microclimate" to see the actions available
 
-## Features
+## Features [(Documentation)](https://microclimate-dev2ops.github.io/mdt-vsc-commands-overview)
 - View all projects in Microclimate, including their app and build statuses
-- Debug **Microprofile, Spring, and Node** Microclimate projects
-- View application and build logs in the Output view
-- View project info (similar to Microclimate Overview page)
+- Debug Microprofile, Spring, and Node.js Microclimate projects
+- View application and build logs in the VSCode *Output* view
+- View project information, similar to the Microclimate *Overview* page
 - Open your applications in the system browser
-- Integrate Microclimate validation errors into the Problems view
+- Integrate Microclimate validation errors into the VSCode *Problems* view
 - Open a shell session into a Microclimate application container
-- Open the App Monitor page
+- Open the *App Monitor* page
 - Toggle project auto-build
-- Easily scope your VSCode workspace to a Microclimate project or your `microclimate-workspace`
 - Manually initiate project builds
-- Disable, Enable, and Delete projects
-
-Link to the documentation
+- Scope your VSCode workspace to a Microclimate project or to your *microclimate-workspace*
+- Disable, enable, and delete projects
 
 ## Contributing
-We welcome issues (make this a link) and contributions from the public! See [CONTRIBUTING.md](https://github.ibm.com/dev-ex/microclimate-vscode/tree/master/CONTRIBUTING.md)
+We welcome [issues](https://github.com/microclimate-dev2ops/microclimate-vscode-tools/issues) and contributions from the public! See [CONTRIBUTING.md](https://github.ibm.com/dev-ex/microclimate-vscode/tree/master/CONTRIBUTING.md).