More documentation updates (#202)

* Add some content to the design page.

* More design doc updates

* Update user guide docs

docs/guide/introduction.md

@@ -4,8 +4,13 @@
 > important information.  If you feel that a particular area is missing or
 > poorly explained, please feel free to file an issue at our [GitHub site](https://github.com/Microsoft/sqltoolsservice/issues)
 
-SQL Tools Service is a tool that provides useful services to code
-editors that need a great SQL Server editing experience.
+SQL Tools Service is a API that provides useful services to database developer 
+and management tools.
+
+## The JSON-RPC API
+The SQL Tools Service exposes its feature set as a JSON-RPC over stdio.  See 
+the API details at [JSON-RPC Protocol](jsonrpc_protocol.md) and checkout some
+usage examples at [Using the JSON-RPC API](using_the_jsonrpc_api.md).
 
 ## The .NET API
 
@@ -13,5 +18,4 @@ The .NET API provides the complete set of services which can be used in
 code editors or any other type of application.
 
 If you're a developer that would like to use SQL Tools Service in
-a .NET application, read the page titled [Using the .NET API](using_the_dotnet_api.md)
-to learn more.
+a .NET application, checkout the [.Net API reference](../api/index.md).

docs/guide/jsonrpc_protocol.md

@@ -1,4 +1,4 @@
-# Using the JSON-RPC API
+# JSON-RPC Protocol
 
 The JSON-RPC API provides an host-agnostic interface for
 leveraging the core .NET API.
@@ -19,28 +19,31 @@ which contains all of the user's SQL script files for a given project.
 
 ## Messages overview
 
+The SQL Tools Service implements portions of the 
+[language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md)
+defined by VS Code.  Some portions of this protocol reference have been duplicated here for 
+convenience.  
+
+It additionally implements several other API to provide database management
+services such as connection management or query execution.
+
+This document provides the protocol specification for all the service's JSON-RPC APIs.
+
 General
 
 * :leftwards_arrow_with_hook: [initialize](#initialize) 
 * :leftwards_arrow_with_hook: [shutdown](#shutdown) 
 * :arrow_right: [exit](#exit) 
 * :arrow_right: [$/cancelRequest](#cancelRequest)
+* :arrow_right: [workspace/didChangeConfiguration](#workspace_didChangeConfiguration) 
+* :arrow_right: [workspace/didChangeWatchedFiles](#workspace_didChangeWatchedFiles) 
 
-Window
+Language Service
 
 * :arrow_left: [window/showMessage](#window_showMessage) 
 * :arrow_right_hook: [window/showMessageRequest](#window_showMessageRequest) 
 * :arrow_left: [window/logMessage](#window_logMessage) 
 * :arrow_left: [telemetry/event](#telemetry_event) 
-
-Workspace
-
-* :arrow_right: [workspace/didChangeConfiguration](#workspace_didChangeConfiguration) 
-* :arrow_right: [workspace/didChangeWatchedFiles](#workspace_didChangeWatchedFiles) 
-* :leftwards_arrow_with_hook: [workspace/symbol](#workspace_symbol) 
-
-Document
-
 * :arrow_left: [textDocument/publishDiagnostics](#textDocument_publishDiagnostics) 
 * :arrow_right: [textDocument/didChange](#textDocument_didChange)  
 * :arrow_right: [textDocument/didClose](#textDocument_didClose) 
@@ -51,18 +54,12 @@ Document
 * :leftwards_arrow_with_hook: [textDocument/hover](#textDocument_hover) 
 * :leftwards_arrow_with_hook: [textDocument/signatureHelp](#textDocument_signatureHelp) 
 * :leftwards_arrow_with_hook: [textDocument/references](#textDocument_references) 
-* :leftwards_arrow_with_hook: [textDocument/documentHighlight](#textDocument_documentHighlight) 
-* :leftwards_arrow_with_hook: [textDocument/documentSymbol](#textDocument_documentSymbol) 
-* :leftwards_arrow_with_hook: [textDocument/formatting](#textDocument_formatting) 
-* :leftwards_arrow_with_hook: [textDocument/rangeFormatting](#textDocument_rangeFormatting) 
-* :leftwards_arrow_with_hook: [textDocument/onTypeFormatting](#textDocument_onTypeFormatting) 
 * :leftwards_arrow_with_hook: [textDocument/definition](#textDocument_definition) 
-* :leftwards_arrow_with_hook: [textDocument/codeAction](#textDocument_codeAction) 
-* :leftwards_arrow_with_hook: [textDocument/codeLens](#textDocument_codeLens) 
-* :leftwards_arrow_with_hook: [codeLens/resolve](#codeLens_resolve) 
-* :leftwards_arrow_with_hook: [textDocument/documentLink](#textDocument_documentLink) 
-* :leftwards_arrow_with_hook: [documentLink/resolve](#documentLink_resolve) 
-* :leftwards_arrow_with_hook: [textDocument/rename](#textDocument_rename) 
+
+Connection Management
+
+Query Execution
+
 
 # Message Protocol
 

docs/guide/toc.md

@@ -1,3 +1,3 @@
 # [Introduction](introduction.md)
-# [Using the JSON-RPC API](using_the_host_process.md)
-# [Using the .NET API](using_the_dotnet_api.md)
+# [JSON-RPC Protocol](jsonrpc_protocol.md)
+# [Using the JSON-RPC API](using_the_jsonrpc_api.md)

docs/guide/using_the_jsonrpc_api.md

@@ -1,4 +1,4 @@
-# Using the SQL Tools Service .NET API
+# Using the JSON-RPC API
 
 > NOTE: The [API Reference](../api/index.md) is the best starting point for working directly with
 > the .NET API.