Update docs (#617)

(cherry picked from commit b6bbcd2)

Author: ospillinger

README.md

@@ -11,25 +11,35 @@ Cortex is an open source platform for deploying machine learning models—traine
 
 ## Key features
 
-- **Autoscaling:** Cortex automatically scales APIs to handle production workloads.
+* **Autoscaling:** Cortex automatically scales APIs to handle production workloads.
+* **Multi framework:** Cortex supports TensorFlow, PyTorch, scikit-learn, XGBoost, and more.
+* **CPU / GPU support:** Cortex can run inference on CPU or GPU infrastructure.
+* **Spot instances:** Cortex supports EC2 spot instances.
+* **Rolling updates:** Cortex updates deployed APIs without any downtime.
+* **Log streaming:** Cortex streams logs from deployed models to your CLI.
+* **Prediction monitoring:** Cortex monitors network metrics and tracks predictions.
+* **Minimal configuration:** Deployments are defined in a single `cortex.yaml` file.
 
-- **Multi framework:** Cortex supports TensorFlow, PyTorch, scikit-learn, XGBoost, and more.
-
-- **CPU / GPU support:** Cortex can run inference on CPU or GPU infrastructure.
-
-- **Spot instances:** Cortex supports EC2 spot instances.
+<br>
 
-- **Rolling updates:** Cortex updates deployed APIs without any downtime.
+## Spinning up a Cortex cluster
 
-- **Log streaming:** Cortex streams logs from deployed models to your CLI.
+Cortex is designed to be self-hosted on any AWS account. You can spin up a Cortex cluster with a single command:
 
-- **Prediction monitoring:** Cortex monitors network metrics and tracks predictions.
+```bash
+$ cortex cluster up
 
-- **Minimal configuration:** Deployments are defined in a single `cortex.yaml` file.
+aws region: us-west-2
+aws instance type: p2.xlarge
+min instances: 0
+max instances: 10
+spot instances: yes
 
-<br>
+￮ spinning up your cluster ...
+your cluster is ready!
+```
 
-## Usage
+## Deploying a model
 
 ### Implement your predictor
 
@@ -94,17 +104,23 @@ negative  4
 
 <br>
 
-## How it works
+## What is Cortex an alternative to?
+
+Cortex is an open source alternative to serving models with SageMaker or building your own model deployment platform on top of AWS services like Elastic Kubernetes Service (EKS), Elastic Container Service (ECS), Lambda, Fargate, and Elastic Compute Cloud (EC2) or open source projects like Docker, Kubernetes, and TensorFlow Serving.
+
+<br>
+
+## How does Cortex work?
 
 The CLI sends configuration and code to the cluster every time you run `cortex deploy`. Each model is loaded into a Docker container, along with any Python packages and request handling code. The model is exposed as a web service using Elastic Load Balancing (ELB), TensorFlow Serving, and ONNX Runtime. The containers are orchestrated on Elastic Kubernetes Service (EKS) while logs and metrics are streamed to CloudWatch.
 
 <br>
 
-## Examples
+## Examples of Cortex deployments
 
 <!-- CORTEX_VERSION_README_MINOR x5 -->
-- [Sentiment analysis](https://github.com/cortexlabs/cortex/tree/0.11/examples/tensorflow/sentiment-analyzer) in TensorFlow with BERT
-- [Image classification](https://github.com/cortexlabs/cortex/tree/0.11/examples/tensorflow/image-classifier) in TensorFlow with Inception
-- [Text generation](https://github.com/cortexlabs/cortex/tree/0.11/examples/pytorch/text-generator) in PyTorch with DistilGPT2
-- [Reading comprehension](https://github.com/cortexlabs/cortex/tree/0.11/examples/pytorch/reading-comprehender) in PyTorch with ELMo-BiDAF
-- [Iris classification](https://github.com/cortexlabs/cortex/tree/0.11/examples/sklearn/iris-classifier) in scikit-learn
+* [Sentiment analysis](https://github.com/cortexlabs/cortex/tree/0.11/examples/tensorflow/sentiment-analyzer): deploy a BERT model for sentiment analysis.
+* [Image classification](https://github.com/cortexlabs/cortex/tree/0.11/examples/tensorflow/image-classifier): deploy an Inception model to classify images.
+* [Search completion](https://github.com/cortexlabs/cortex/tree/0.11/examples/tensorflow/search-completer): deploy Facebook's RoBERTa model to complete search terms.
+* [Text generation](https://github.com/cortexlabs/cortex/tree/0.11/examples/pytorch/text-generator): deploy Hugging Face's DistilGPT2 model to generate text.
+* [Iris classification](https://github.com/cortexlabs/cortex/tree/0.11/examples/sklearn/iris-classifier): deploy a scikit-learn model to classify iris flowers.

docs/cluster/aws.md renamed to docs/cluster-management/aws.md

@@ -42,8 +42,8 @@ cortex get classifier
 
 # classify a sample
 curl -X POST -H "Content-Type: application/json" \
-     -d '{ "sepal_length": 5.2, "sepal_width": 3.6, "petal_length": 1.4, "petal_width": 0.3 }' \
-     <API endpoint>
+  -d '{ "sepal_length": 5.2, "sepal_width": 3.6, "petal_length": 1.4, "petal_width": 0.3 }' \
+  <API endpoint>
 ```
 
 ## Cleanup

docs/cluster/cli.md renamed to docs/cluster-management/cli.md

@@ -1,13 +1,13 @@
-# Development Environment
+# Development
 
 ## Prerequisites
 
 1. Go (>=1.12.9)
-1. Docker
-1. eksctl
-1. kubectl
+2. Docker
+3. eksctl
+4. kubectl
 
-## Cortex Dev Environment
+## Cortex dev environment
 
 Clone the project:
 
@@ -109,7 +109,7 @@ make cli  # The binary will be placed in path/to/cortex/bin/cortex
 path/to/cortex/bin/cortex configure
 ```
 
-### Cortex Cluster
+### Cortex cluster
 
 Start Cortex:
 
@@ -123,35 +123,35 @@ Tear down the Cortex cluster:
 make cortex-down
 ```
 
-### Deployment an Example
+### Deploy an example
 
 ```bash
 cd examples/iris-classifier
 path/to/cortex/bin/cortex deploy
 ```
 
-## Off-cluster Operator
+## Off-cluster operator
 
 If you're making changes in the operator and want faster iterations, you can run an off-cluster operator.
 
 1. `make operator-stop` to stop the in-cluster operator
-1. `make devstart` to run the off-cluster operator (which rebuilds the CLI and restarts the Operator when files change)
-1. `path/to/cortex/bin/cortex configure` (on a separate terminal) to configure your cortex CLI to use the off-cluster operator. When prompted for operator URL, use `http://localhost:8888`
+2. `make devstart` to run the off-cluster operator (which rebuilds the CLI and restarts the Operator when files change)
+3. `path/to/cortex/bin/cortex configure` (on a separate terminal) to configure your cortex CLI to use the off-cluster operator. When prompted for operator URL, use `http://localhost:8888`
 
 Note: `make cortex-up-dev` will start Cortex without installing the operator.
 
 If you want to switch back to the in-cluster operator:
 
 1. `<ctrl+C>` to stop your off-cluster operator
-1. `make operator-start` to install the operator in your cluster
-1. `path/to/cortex/bin/cortex configure` to configure your cortex CLI to use the in-cluster operator. When prompted for operator URL, use the URL shown when running `make cortex-info`
+2. `make operator-start` to install the operator in your cluster
+3. `path/to/cortex/bin/cortex configure` to configure your cortex CLI to use the in-cluster operator. When prompted for operator URL, use the URL shown when running `make cortex-info`
 
-## Dev Workflow
+## Dev workflow
 
 1. `make cortex-up-dev`
-1. `make devstart`
-1. Make changes
-1. `make registry-dev`
-1. Test your changes with projects in `examples` or your own
+2. `make devstart`
+3. Make changes
+4. `make registry-dev`
+5. Test your changes with projects in `examples` or your own
 
 See `Makefile` for additional dev commands