improved README (#270)

README.md

@@ -2,58 +2,46 @@
 [![Build
 Status](https://travis-ci.org/helm/monocular.svg?branch=master)](https://travis-ci.org/helm/monocular)
 
-Monocular is a part of the Helm project and aims to provide a way to search for and discover apps that have been packaged in Helm
-Charts. Monocular includes a scanning back-end for indexing charts and their metadata and a simple user interface.
+Monocular is web-based UI for managing Kubernetes applications packaged as Helm
+Charts. It allows you to search and discover available charts from multiple
+repositories, and install them in your cluster with one click.
 
-A monocular is a single-lensed telescope, and perhaps a twee synonym for the kind of kit that would be useful when inspecting a disordered stack of nautical charts, like a magnifying glass or microscope with a spyglass aesthetic. Its adjectival form suggests a Cyclops, with whom Oddysseus was definitely on familiar terms; and its closest synonym is monocle, a well-worn accoutrement of Victorian Great Britain, surely the greatest of all naval empires. `kubernetes` indeed.
-
-As with The Beatles, some things are better in mono.
+![Monocular Screenshot](docs/MonocularScreenshot.gif)
 
 See Monocular in action at [KubeApps.com](https://kubeapps.com) or click [here](docs/about.md) to learn more about Helm, Charts and Kubernetes.
 
-## Development
-
-### App Structure
-
-Monocular comprises a UI front end, and a RESTFul HTTP back end API.
-
-#### UI Prerequisites
-
-The UI is an angular 2 client application located in `src/ui/`.
-
-More UI docs are [here](src/ui/README.md).
-
-#### API Prerequisites
+##### Video links
+- [Screencast](https://www.youtube.com/watch?v=YoEbvDrI5ng)
+- [Helm and Monocular Webinar](https://www.youtube.com/watch?v=u8kDkHgRbWQ)
 
-The API is a golang HTTP server located in `src/api/`.
+## Install
 
-`Makefile` assumes [docker](https://www.docker.com) for containerized development; and [glide](http://glide.sh) for dependency enforcement.
+You can use the chart in this repository to install Monocular in your cluster.
 
-`cd src/api/ && make bootstrap` will launch a docker container, and run a `glide install` command to install all API dependencies in the `src/api/vendor/` directory.
+##### Prerequisites
+- [Helm and Tiller installed](https://github.com/kubernetes/helm/blob/master/docs/quickstart.md)
+- [Nginx Ingress controller](https://github.com/kubernetes/ingress)
 
-More API docs are [here](src/api/README.md).
+```console
+$ git clone https://github.com/helm/monocular.git
+$ cd ./monocular
+$ helm install ./deployment/monocular
+```
 
-### Running a development environment
+Read more on how to deploy Monocular [here](docs/deployment.md).
 
-We leverage [docker](https://www.docker.com) (via `docker-compose`) to provide a multi-tier setup for development.
+## Documentation
 
-Running `docker-compose up` from the root directory will expose:
-
-* API backend endpoint via `http://{your-docker-machine-ip-address}:8080`
-* UI frontend via `http://{your-docker-machine-ip-address}:4200`  
-
-**IMPORTANT**:
-* If your Docker Machine hostname is different than *localhost*, you need to change
-the `backendHostname` value in the file `src/ui/src/app/shared/services/config.service.ts`.
-
-You can restart individual services doing `docker-compose restart api|ui`
-
-## Deploy in Kubernetes
-
-More information on how to deploy your own instance of Monocular in Kubernetes [here](docs/deployment.md).
+- [Configuration](docs/configuration.md)
+- [Deployment](docs/deployment.md)
+- [Development](docs/development.md)
 
 ## Contribute
 
-This project is still under active development, so you'll likely encounter [issues](https://github.com/helm/monocular/issues).
+This project is still under active development, so you'll likely encounter
+[issues](https://github.com/helm/monocular/issues).
+
+Interested in contributing? Check out the [documentation](CONTRIBUTING.md).
 
-Please participate by filing issues or contributing a pull request!
+Also see [developer's guide](docs/development.md) for information on how to
+build and test the code.

docs/development.md

@@ -0,0 +1,36 @@
+# Development
+
+## App Structure
+
+Monocular comprises a UI front end, and a RESTFul HTTP back end API.
+
+### UI Prerequisites
+
+The UI is an angular 2 client application located in `src/ui/`.
+
+More UI docs are [here](src/ui/README.md).
+
+### API Prerequisites
+
+The API is a golang HTTP server located in `src/api/`.
+
+`Makefile` assumes [docker](https://www.docker.com) for containerized development; and [glide](http://glide.sh) for dependency enforcement.
+
+`cd src/api/ && make bootstrap` will launch a docker container, and run a `glide install` command to install all API dependencies in the `src/api/vendor/` directory.
+
+More API docs are [here](src/api/README.md).
+
+## Running a development environment
+
+We leverage [docker](https://www.docker.com) (via `docker-compose`) to provide a multi-tier setup for development.
+
+Running `docker-compose up` from the root directory will expose:
+
+* API backend endpoint via `http://{your-docker-machine-ip-address}:8080`
+* UI frontend via `http://{your-docker-machine-ip-address}:4200`  
+
+**IMPORTANT**:
+* If your Docker Machine hostname is different than *localhost*, you need to change
+the `backendHostname` value in the file `src/ui/src/app/shared/services/config.service.ts`.
+
+You can restart individual services doing `docker-compose restart api|ui`