Merge pull request #19 from whisk-ml/readme_consolidate

Update main readme and link bike example

README.md

@@ -4,95 +4,40 @@
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/whisk)](https://pypi.python.org/pypi/whisk)
 [![docs](https://readthedocs.org/projects/whisk/badge/?version=latest)](https://whisk.readthedocs.io/en/latest/?badge=latest)
 
-**[whisk](https://whisk.readthedocs.io/en/latest/) is a ML project framework that make makes collaboration, reproducibility, and deployment "just work".**
+__whisk is an open-source ML project framework that makes collaboration, reproducibility, and deployment "just work".__ It combines a suite of lightweight tools with a logical and flexible project structure. Release your model to the world without a software engineer.
 
-Tying together the tools required to release a machine learning model can be daunting. Whisk makes building and releasing ML models easy and fun. Whisk creates a logical and flexible project structure for ML with reproducible results and lets you release your model to the world without becoming a software engineer.
-
-Whisk doesn't lock you into a particular ML framework or require you to learn yet another ML packaging API. Instead, it leverages the magic of Python's ecosystem that's available to projects structured in a Pythonic-way. Whisk does the structuring while you focus on the data science.
+Whisk doesn't lock you into a particular ML framework or require you to learn yet another ML packaging API. Instead, it lets you leverage the large Python ecosystem by structuring your ML project in a [Pythonic-way](
+https://docs.python-guide.org/writing/structure/). Whisk does the structuring while you focus on the data science.
 
 Read more about our [beliefs](#beliefs).
 
-## Quickstart
-
-_Replace `demo` with the name of your ML project in the examples below._
-
-### Create a project for the model
+## Getting Started
 
-Create the project with whisk:
+Start by creating a project. Begin a terminal session and run the commands below. _Note: We use __demo__ as the project name in the examples below. If you use a different project name, be sure to replace __demo__ with the name of your project._
 
 ```
 $ pip install whisk
-$ echo "Generate the directory structure, set up a venv, initialize a Git repo, and more."
 $ whisk create demo
 $ cd demo
 $ source venv/bin/activate
 ```
 
-Take a quick tour the project you just created:
-
-```
-$ jupyter-notebook notebooks/getting_started.ipynb
-```
-
-The notebook shows how to save your trained model to disk, use the saved model to generate predictions, how to load Python functions and classes from the project's `src` directory for a cleaner notebook, and more. It's the guide rails for your own ML project.
-
-### Test the model
-
-Once you've created a model with whisk, it's easy to test locally.
-
-There's a placeholder model you can invoke immediately from the command line:
-
-```
-$ demo predict [[0,1],[2,3]]
-[2, 2]
-```
-
-...and within Python code:
-
-```py
-from demo.models.model import Model
-model = Model()
-model.predict([[0,1],[2,3]])
-```
-
-### Share and deploy the model
+The commands above do the following:
 
-After you develop and test your model, it's time to share.
+* [Install the whisk package](https://whisk.readthedocs.io/en/latest/installation.html)
+* [Create a project](https://whisk.readthedocs.io/en/latest/cli_reference.html#whisk-create) named "demo"
+* [Generate the project directory structure](https://whisk.readthedocs.io/en/latest/project_structure.html)
+* Activate the project's venv
 
-Create a **Python package** containing your model and share with the world:
+__To try out all of the features, continue the [quick tour of whisk →](tour_of_whisk.html#try-the-sample-model).__
 
-```
-$ whisk package dist
-Python Package created in /Users/dlite/projects/whisk_examples/demo/dist:
-demo-0.1.0.tar.gz
-
-$ pip install dist/demo-0.1.0.tar.gz
-```
-
-... or create a **ready-to-go Flask web service**:
-
-```
-$ whisk app start
-$ curl --location --request POST 'http://localhost:5000/predict' \
---header 'Content-Type: application/json' \
---data-raw '{"data":[[0, 1], [2, 3]]}'
-```
-
-... and **deploy the web service to Heroku** ([a free account is fine](https://signup.heroku.com/)):
-
-```
-$ whisk app create demo-[INSERT YOUR NAME]
-```
-
-## Whisk CLI Commands
-
-To see a list of available whisk commands and command groups:
-
-    whisk --help
+## Examples
 
-You can view help on specific command groups like this:
+The [whisk-ml](https://github.com/whisk-ml) GitHub org contains example whisk projects. Check out these examples and clone them locally. Since whisk makes reproducibility "just work", in most cases you simply need to run [`whisk setup`](https://whisk.readthedocs.io/en/latest/cli_reference.html#whisk-setup) to use the models generated by the projects. Here are few examples to start with:
 
-    whisk app --help
+* [Text Classification with Pytorch](#)
+* [Image Classification with Tensorflow](https://github.com/whisk-ml/bike_image_classifier_tensorflow)
+* Iris Classification with SKLearn (Coming soon)
 
 ## Beliefs
 
@@ -103,9 +48,6 @@ You can view help on specific command groups like this:
 * **Docker and Kubernetes are usually not needed** - when we [explicitly declare and isolate dependencies](https://12factor.net/dependencies), we don't need to rely on the implicit existence of packages installed in a Docker container. Docker also creates a slow development flow: repeatedly restarting Docker containers is far slower than doing the same in pure Python. Python already has solid native tools for this problem.
 * **Optimize for debugging** - 90% of writing software is fixing bugs. It should be easy to debug your model logic locally. You should be able to search your error and find results, not sift through custom package source code.
 
-## Examples
-
-Check out whisk example projects in [the whisk GitHub organization](https://github.com/whisk-ml).
 
 ## Contributing
 

docs/index.md

@@ -31,9 +31,9 @@ __To try out all of the features, continue the [quick tour of whisk →](tour_of
 
 The [whisk-ml](https://github.com/whisk-ml) GitHub org contains example whisk projects. Check out these examples and clone them locally. Since whisk makes reproducibility "just work", in most cases you simply need to run [`whisk setup`](cli_reference.html#whisk-setup) to use the models generated by the projects. Here are few examples to start with:
 
-* [Iris Classification with SKLearn](#)
-* [Text Classification with Pytorch](#)
-* [Image Classification with Tensorflow](#)
+* [Text Classification with Keras and Tensorflow](https://github.com/whisk-ml/disaster_tweets) - A model that predicts which tweets are about real disasters and which ones are not. This project uses DVC to version control the data download and training stages.
+* [Image Classification with Tensorflow](https://github.com/whisk-ml/bike_image_classifier_tensorflow) - A classifier to determine if an image is of a Mountain bike or a Road bike.
+* Iris Classification with SKLearn (Coming soon)
 
 ## Documentation