readme: write up a summary version

README.md

@@ -2,56 +2,59 @@
 
 # k6 Operator
 
-`grafana/k6-operator` is a Kubernetes operator for running distributed k6 tests in your cluster.
+`grafana/k6-operator` is a Kubernetes operator for running distributed [k6](https://github.com/grafana/k6) tests in your cluster. k6 Operator introduces two CRDs:
+- `TestRun` CRD
+- `PrivateLoadZone` CRD
 
-Read also the [complete tutorial](https://k6.io/blog/running-distributed-tests-on-k8s/) to learn more about how to use this project.
+`TestRun` CRD is a representation of a single k6 test, executed once. `TestRun` has a large support for configuration of different options that allows you to adapt to different Kubernetes setups. Some frequently used options are described [here](TODO), and full list of options can be found in the [definition itself](https://github.com/grafana/k6-operator/blob/main/config/crd/bases/k6.io_testruns.yaml).
 
-## Setup
+`PrivateLoadZone` CRD is a representation of a [load zone](https://grafana.com/docs/grafana-cloud/testing/k6/author-run/use-load-zones/): a k6 term for a set of nodes within a cluster designated to execute k6 test runs. `PrivateLoadZone` is integrated with [Grafana Cloud k6](https://grafana.com/products/cloud/k6/) and requires a [Grafana Cloud account](https://grafana.com/auth/sign-up/create-user). There is a guide describing [how to set up `PrivateLoadZone`](https://grafana.com/docs/grafana-cloud/testing/k6/author-run/set-up-private-load-zones/), while billing details can be found [here](TODO).
 
-REMOVED
+## Documentation
 
-## Usage
+Complete documentation for the k6 Operator is part of the [Grafana docs](TODO). There are some additional resources:
 
-Samples are available in `config/samples` and `e2e/`, both for `TestRun` and for `PrivateLoadZone`.
+- :book: A guide [Running distributed load tests on Kubernetes](https://grafana.com/blog/2022/06/23/running-distributed-load-tests-on-kubernetes/).
+- :book: A guide [Running distributed tests](https://grafana.com/docs/k6/latest/testing-guides/running-distributed-tests/).
+- :movie_camera: Grafana Office Hours [Load Testing on Kubernetes with k6 Private Load Zones](https://www.youtube.com/watch?v=RXLavQT58YA).
 
-REMOVED
+Common samples are available in `config/samples` and `e2e/` of this repo, both for the `TestRun` and for the `PrivateLoadZone`.
 
-## Uninstallation
+## Contributing
 
-You can remove the all resources created by the operator with bundle:
-```bash
-curl https://raw.githubusercontent.com/grafana/k6-operator/main/bundle.yaml | kubectl delete -f -
-```
+### Requests and feedback
 
-Or with `make` command:
-```bash
-make delete
-```
+We are always interested in your feedback! If you encounter problems during the k6 Operator usage, check out the [troubleshooting guide](TODO). If there are questions about the k6 Operator usage, you can write them on [Grafana community forum](https://community.grafana.com/c/grafana-k6/k6-operator/73).
 
-## Developing Locally
+For new feature requests and bug reports, consider opening an issue in this repository. First check the [existing issues](https://github.com/grafana/k6-operator/issues) in case a similar report already exists. If it does, add a comment about your use case or upvote it.
 
-### Pre-Requisites
+For bug reports, please use [this template](https://github.com/grafana/k6-operator/issues/new?assignees=&labels=bug&projects=&template=bug.yaml). If you think there is a missing feature, please use [this template](https://github.com/grafana/k6-operator/issues/new?assignees=&labels=enhancement&projects=&template=feat_req.yaml).
 
-- [operator-sdk](https://sdk.operatorframework.io/docs/installation/)
-- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/)
+### Development
+
+<!-- TODO: pull out into contributing guide -->
 
-### Run Tests
+It is preferable to work on an open issue when submitting a PR. If such an issue does not exist, create it. An issue allows to validate the problem, gather additional feedback from community and to avoid doing unnecessary work.
 
-#### Test Setup
+<!-- 
+Some Github issues have ["good first issue" label](https://github.com/grafana/k6-operator/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22): these are the issues that should be good for newcomers. The issues with ["help wanted" label](https://github.com/grafana/k6-operator/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) are the ones that could use some community help or additional user feedback. -->
 
-- `make test-setup` (only need to run once)
+There are many options to have a local Kubernetes cluster for development: any of them can be used for local development of the k6 Operator. One of such options it to create a [kind cluster](https://kind.sigs.k8s.io/docs/user/quick-start/).
 
-#### Run Unit Tests
+Additionally, you'll need to install the following tooling:
+- [Golang](https://go.dev/doc/install)
+- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/)
+- [operator-sdk](https://sdk.operatorframework.io/docs/installation/): optional as most common changes can be done without it
+
+To execute unit tests, use these commands:
 
-- `make test`
+```bash
+make test-setup # only need to run once
+make test
+```
 
-#### Run e2e Tests
+To execute e2e test locally:
 
-- [install kind and create a k8s cluster](https://kind.sigs.k8s.io/docs/user/quick-start/) (or create your own dev cluster)
-- `make e2e` for kustomize and `make e2e-helm` for helm
+- `make e2e` for kustomize and `make e2e-helm` for Helm
 - validate tests have been run
 - `make e2e-cleanup`
-
-## See also
-
-- [Running distributed k6 tests on Kubernetes](https://k6.io/blog/running-distributed-tests-on-k8s/)