update README.md

Author: Kerry Chang

README.md

@@ -6,10 +6,50 @@
 
 # IBM Cloud Functions Shell
 
-Welcome to a new development experience for IBM Cloud Functions.
+Welcome to a new development experience for IBM Cloud Functions. Cloud Functions Shell (or just _Shell_) is an [Electron](https://electronjs.org/) desktop application that combines a command-line interface (CLI) and a graphical user interface (GUI): 
+
+* Developers interact with the cloud mainly through execute textual commands, as in a conventional CLI. The command-line style of interaction enables quick task switching without clicking through various links and allows task automation through scripting. 
+* Unlike conventional CLIs, in Shell, data returned from the cloud are carefully rendered into prettified code, tables and visualizations to assist users in various tasks. Mouse interactions are added to avoid copying lengthy text or IDs. Shell also integrates some common graphical tools such as a debugger for inspecting parameters and inserting breakpoints, and an light-weight text editor that offers real-time syntax highlighting. 
+
+As a local desktop application, Shell is fast and is designed for productive use, and can access local storage to provide new features like interacting with other editors and debugging a function in a local container. 
+
+## Installing Shell
+Shell is currently distributed through the [Node.js package manager (NPM)](https://www.npmjs.com/package/@ibm-functions/shell). We recommend that you install the shell globally (`npm install -g`): 
+
+```
+$ npm install -g @ibm-functions/shell
+```
+
+If you are an existing `wsk` or `bx wsk` CLI user, you should be able to start using Shell right away with the host and credential specified in `$HOME/.wskprops`. If you have never installed `bx wsk` or `wsk` CLI before, follow the instructions in the [install and troubleshooting page](docs/npm.md#using-shell-with-ibm-cloud-functions-or-apache-openwhisk) to set up your environment. 
+
+## Starting Shell 
+
+```
+$ fsh shell
+```
+
+`fsh` is a shorthand for "function shell". You will see a new window popped up. Welcome to Shell! 
+
+_Tip_: You can ping Shell's icon to the desktop for quick access. For example, in MacOS, you can right click on the blue Shell icon and select `Options > Keep in Dock`. Next time you can click on that icon to start Shell from the dock. 
+
+## Interface Overview
+
+|<img src="docs/figures/ui-overview.gif" width="90%" title="Shell UI Overview">|
+|:--:|
+|Working in Shell|
+
+Shell has a CLI and a _sidecar_ that can be opened and closed on demand. Contents that need more space such as JSON data or visualizations are usually shown in the sidecar, whereas execution messages and lists are shown under the corresponding command. 
+
+## Learning Shell 
+
+* Basic cloud function commands (TODO)
+* Run Shell commands in the Electron app vs. directly from the terminal (TODO)
+* [Programming Serverless Composition with Composer and Shell](https://github.com/ibm-functions/composer/blob/master/docs/tutorials/introduction/README.md) 
+* Tour of Shell's visualizations (TODO)
+* [Shell's YouTube channel](https://www.youtube.com/channel/UCcu16nIMNclSujJWDOgUI_g) for demo videos 
+
+## Developing Shell together
+
+Contributions are welcome. Please join in [developing and extending the Shell code](docs/dev/README.md).
+
 
-- [About the shell](docs/fsh.md)
-- [Installation](docs/npm.md)
-- Tutorials (TODO)
-- [Using the shell for serverless compositions](https://github.com/ibm-functions/composer/blob/master/docs/README.md#tour-of-the-programming-shell)
-- Contributions are welcome. Please join in [developing and extending the Shell code](docs/dev/README.md).

docs/figures/ui-overview.gif

@@ -1,6 +1,7 @@
-## Installing the shell with `npm`
+# Setting up Cloud Function Shell 
 
-The programming shell is currently distributed through the [Node
+## Installing Shell
+Shell is currently distributed through the [Node
 package manager](https://www.npmjs.com/package/@ibm-functions/shell).
 
 ```bash
@@ -20,6 +21,16 @@ We also recommend using the `Node.js`
 `node v8`. If you're using `npm v3.10.x` you may encounter permissions
 issues. In this case, upgrade your `npm` and try again.
 
+## Using Shell with IBM Cloud Functions or Apache OpenWhisk
+Currently, most Shell commands are for interacting with [Apache OpenWhisk](https://openwhisk.apache.org/), an open source serverless cloud platform. You can setup Shell to communicate with [IBM Cloud Functions](https://console.bluemix.net/openwhisk/) which is based on OpenWhisk, or your own locally deployed OpenWhisk instance. 
+
+Note that if you are an exiting `bx wsk` or `wsk` CLI user, you should be able to [run Shell right away](../README.md#starting-shell). If you have never installed `bx wsk` or `wsk` CLI before, follow the instructions below to set up your environment: 
+
+* _Run Shell with IBM Cloud Functions_: You need to have an [IBM Cloud account](https://www.ibm.com/cloud/), and follow the instructions [here](https://console.bluemix.net/openwhisk/learn/cli) to login to the IBM Cloud and verify your setup. 
+
+* _Run Shell with Apache OpenWhisk_: you need a valid `$HOME/.wskprops` file and a [locally deployed OpenWhisk instance](https://github.com/apache/incubator-openwhisk#quick-start).
+
+## Updating Shell
 We roll out frequent updates and bug fixes. You can check for new
 releases via `fsh version -u`.