Docimprovements (#556)

* concepts

* readme update

README.md

@@ -1,6 +1,9 @@
 # Iter8
 ![Iter8 illustration](mkdocs/src/assets/images/ghbanner.png)
 
+## Welcome
+Welcome to the Iter8 GitHub repo! For Iter8 project documentation, please visit the following links.
+
 ## [Iter8 Documentation](https://iter8.tools)
 
 ## [Quick Start in 5 mins](https://iter8.tools/getting-started/quick-start/with-knative/)

mkdocs/docs/concepts/experimentationstrategies.md

@@ -102,7 +102,7 @@ Iter8 enables you to take total advantage of all the traffic shaping features av
     ![Canary](/assets/images/request-routing.png)
 
     !!! tip ""
-        Try an experiment with [traffic segmentation](/code-samples/knative/request-routing/).
+        Try an experiment with [traffic segmentation](/code-samples/knative/traffic-segmentation/).
 
 
 ### Version promotion

mkdocs/docs/concepts/features.md

@@ -0,0 +1,24 @@
+---
+template: overrides/main.html
+hide:
+- toc
+---
+
+# Iter8 Features at a Glance
+
+Iter8 enables app/ML model developers, service operators, SREs, ML engineers, and data scientists to achieve the following goals.
+
+- Automate validation/releases over **any** cloud stack; tutorials are documented for **Knative**, **KFServing**[^1] and **Istio**[^2].
+- Declaratively specify validation/release goals using an **experiment** - Kubernetes custom resource defined by Iter8.
+- **Conformance** and **Canary** testing.
+- **Progressive**, **fixed-split**, and **dark-launched** deployments.
+- Specify SLOs and SLIs.
+- **Traffic mirroring** and **traffic segmentation**.
+- Use Helm, Kustomize, and plain YAML/JSON manifests.
+- Use Out-of-the-box metrics custom metrics that can be defined using metrics in **Prometheus**.
+- Statistically rigorous evaluation of versions, traffic splitting, and promotion/rollback decisions using **Bayesian learning** and **multi-armed bandit** algorithms.
+- Observe experiments in realtime.
+
+
+[^1]: An initial version of Iter8 for KFServing is available [here](https://github.com/iter8-tools/iter8-kfserving). An updated version is coming soon.
+[^2]: An earlier version of Iter8 for Istio is available [here](https://github.com/iter8-tools/iter8). An updated version is coming soon.

mkdocs/docs/concepts/whatisiter8.md

@@ -4,35 +4,17 @@ template: overrides/main.html
 
 # What is Iter8?
 
-**Iter8** is an AI-powered platform for cloud native release automation and experimentation. Iter8 makes it easy to unlock business value and guarantee SLOs by identifying the best performing app/ML model version (`winner`) and rolling it out safely.
+**Iter8** is an AI-powered platform for cloud native release automation and experimentation. Iter8 makes it easy to unlock business value and guarantee SLOs by identifying the best performing app/ML model version and rolling it out safely.
 
-Use Iter8 to automate progressive delivery, validation, and promotion/rollback of new versions, and maximize release velocity with confidence while protecting end-user experience.
+Iter8 is designed for **developers, SREs, service operators, data scientists, and ML engineers** who wish to maximize release velocity and/or business value with their apps/ML models while protecting end-user experience.
 
 ## What is an Iter8 experiment?
-Iter8 defines a Kubernetes resource called **Experiment** that automates validation and release of new versions as depicted in the picture below.
+Iter8 defines a Kubernetes resource called **Experiment** that automates progressive delivery, validation, and promotion/rollback of app/ML model versions as depicted below.[^1] 
 
 ![Process automated by an Iter8 experiment](/assets/images/whatisiter8.png)
 
 ## How does Iter8 work?
 
-Iter8 consists of a [Kubernetes controller](https://github.com/iter8-tools/etc3) that orchestrates (reconciles) experiments in conjunction with the [Iter8 analytics service](https://github.com/iter8-tools/iter8-analytics), and the [Iter8 task handler](https://github.com/iter8-tools/handler).
+Iter8 consists of a [Go-based Kubernetes controller](https://github.com/iter8-tools/etc3) that orchestrates (reconciles) experiments in conjunction with a [Python-based analytics service](https://github.com/iter8-tools/iter8-analytics), and a [Go-based task runner](https://github.com/iter8-tools/handler).
 
-## Features at a glance
-
-- Iter8 is designed to support release automation and experimentation over **any** cloud stack; documented code-samples are currently available for **Knative**, **KFServing**[^1] and **Istio**[^2].
-- **Conformance** and **Canary** testing.
-- **Progressive**, **FixedSplit**, and **DarkLaunch** deployments.
-- Traffic shaping methods such as **mirroring** and **traffic segmentation**.
-- Integration with app config tools such as **Helm**, **Kustomize**, and `kubectl`.
-- Out-of-the-box metrics shipped with Iter8 and custom metrics that can be defined using metrics in **Prometheus**.
-- Statistically robust version assessments and decision making during experiments using **Bayesian learning** and **multi-armed bandit** algorithms.
-- The `iter8ctl` CLI for observing experiments in realtime.
-
-
-<!-- orchestrate experiments. These components automate several functions including executing start up tasks that initialize a partially specified experiment, verifying that conditions needed for the experiment are satisfied, iteratively deciding how to split traffic between app versions, identifying a `winner`, error handling, deciding when to terminate the experiment, promoting the `winner`, and executing clean up tasks. -->
-
-<!-- ??? info "Deeper look into Iter8's component interactions"
-    ![Under the hood](/assets/images/under-the-hood.png) -->
-
-[^1]: An initial version of Iter8 for KFServing is available [here](https://github.com/iter8-tools/iter8-kfserving). An updated version is coming soon.
-[^2]: An earlier version of Iter8 for Istio is available [here](https://github.com/iter8-tools/iter8). An updated version is coming soon.
+[^1]: Boxes with dashed boundaries in the picture are optional in an experiment.

mkdocs/mkdocs.yml

@@ -95,6 +95,7 @@ nav:
   - Home: index.md
   - Concepts:
     - What is Iter8?: concepts/whatisiter8.md
+    - Features: concepts/features.md
     - Building blocks of an experiment: concepts/experimentationstrategies.md
   - Getting Started:
     - Quick start: 
@@ -103,13 +104,13 @@ nav:
       - with Istio: getting-started/quick-start/with-istio.md
     - Install: getting-started/install.md
     - Getting help: getting-started/help.md
-  - Validation and Release Strategies + Code:
+  - Tutorials:
     - Knative:
       - Progressive canary release: code-samples/knative/canary-progressive.md
       - Fixed split canary release: code-samples/knative/canary-fixedsplit.md
       - Conformance testing: code-samples/knative/conformance.md
       - Conformance testing with traffic mirroring: code-samples/knative/mirroring.md
-      - Progressive canary release with traffic segmentation: code-samples/knative/request-routing.md
+      - Progressive canary release with traffic segmentation: code-samples/knative/traffic-segmentation.md
       - Useful Knative annotations: code-samples/knative/annotations.md
     - Generating requests externally: code-samples/traffic.md
   - Reference:

mkdocs/src/overrides/main.html

@@ -58,8 +58,6 @@
 
 <!-- Announcement bar -->
 {% block announce %}
-<strong>Iter8</strong> at <a href="https://calendar.google.com/calendar/event?eid=NWZpdWVzcTVkcjRwazRxNnRtcmF1dDV0YW9fMjAyMTAzMjRUMTYzMDAwWiBrbmF0aXZlLnRlYW1fOXE4M2JnMDdxczViOXJyc2xwNWpvcjRsNnNAZw&ctz=GMT-04:00">Knative Community Meetup</a>.
-
 <strong>Iter8</strong> at <a href="https://sched.co/iE2l">KubeCon + CloudNativeCon Europe 2021</a>. For more updates and support, 
     <a href="https://iter8-tools.slack.com">
       join <strong>Iter8</strong> workspace on <span class="twemoji">