diff --git a/README.md b/README.md
index 75a04d3..c1bc6a9 100644
--- a/README.md
+++ b/README.md
@@ -2,3 +2,50 @@
 
 [![Contributor-Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-fbab2c.svg)](CODE_OF_CONDUCT.md)
 [![Maintainer](https://img.shields.io/badge/Maintainer-Cisco-00bceb.svg)](https://opensource.cisco.com)
+
+Application Simulator allows you to rapidly create a set of interacting services, databases and load generators to
+simulate application deployments of any size and form.
+
+Unlike other simulators or demo applications it is not focused around a specific kind of application, like a blog, task
+list, web shop or banking app. Instead, Application Simulator is driven by configuration files that define the behavior
+of the components of your application.
+
+This is especially useful for use cases, where you care less about the business logic to be mimicked, but the interaction
+of the different components that make up an application.
+
+This includes the following use cases:
+
+* Tailored demo environments for observability, e.g. instrumenting all services with OpenTelemetry and visualizing the
+  data in your preferred backend.
+* Complex simulated environments for in-cluster network experiments, e.g. testing out new features of cilium.
+
+## Quick Start
+
+You can use application simulator with your preferred container orchestration, since all components are available as
+container images. We provide the best experience for docker compose and kubernetes. Pick one of them for a quick start!
+
+* [kubernetes quick start](./docs/quick-start/kubernetes.md)
+* [docker compose quick start](./docs/quick-start/docker-compose.md)
+
+## Tutorial
+
+After you have tried out application simulator with the quick start, you can learn using it with the step by step tutorial:
+
+1. [Two java services](./docs/tutorial/1-two-java-services.md)
+2. [A database and more services](./docs/tutorial/2-a-database-and-more-services.md)
+3. [Errors and randomness](./docs/tutorial/3-errors-and-randomness.md)
+4. [Observability with OpenTelemetry](./docs/tutorial/4-observability-with-opentelemetry.md)
+
+## Configuration specification
+
+Application simulator is driven by configuration files that allow you to easily describe a micro service architecture and
+then run it with your preferred container orchestration. The configuration file follows a [specification](./docs/specification.md)
+
+## Contribute
+
+If you'd like to contribute to this project, check out our [contribution guidelines](./CONTRIBUTING.md).
+
+## Support
+
+If you have any questions or concerns, get in touch with us by [raising an issue](https://github.com/cisco-open/app-simulator/issues).
+If you want to report a security issue, please follow our [security policy](./SECURITY.md)
\ No newline at end of file
diff --git a/docs/quick-start/docker-compose.md b/docs/quick-start/docker-compose.md
new file mode 100644
index 0000000..8a7afc1
--- /dev/null
+++ b/docs/quick-start/docker-compose.md
@@ -0,0 +1,3 @@
+# docker compose quick start
+
+to be done
\ No newline at end of file
diff --git a/docs/quick-start/kubernetes.md b/docs/quick-start/kubernetes.md
new file mode 100644
index 0000000..a7cce1d
--- /dev/null
+++ b/docs/quick-start/kubernetes.md
@@ -0,0 +1,3 @@
+# kubernetes quick start
+
+to be done
\ No newline at end of file
diff --git a/docs/specification.md b/docs/specification.md
new file mode 100644
index 0000000..9c1aed0
--- /dev/null
+++ b/docs/specification.md
@@ -0,0 +1,3 @@
+# Application Simulator Configuration Specification
+
+to be done
\ No newline at end of file
diff --git a/docs/tutorial/1-two-java-services.md b/docs/tutorial/1-two-java-services.md
new file mode 100644
index 0000000..e28da66
--- /dev/null
+++ b/docs/tutorial/1-two-java-services.md
@@ -0,0 +1 @@
+# Tutorial 1: Two java services
\ No newline at end of file
diff --git a/docs/tutorial/2-a-database-and-more-services.md b/docs/tutorial/2-a-database-and-more-services.md
new file mode 100644
index 0000000..1abd59f
--- /dev/null
+++ b/docs/tutorial/2-a-database-and-more-services.md
@@ -0,0 +1 @@
+# Tutorial 2: A database and more services
\ No newline at end of file
diff --git a/docs/tutorial/3-errors-and-randmoness.md b/docs/tutorial/3-errors-and-randmoness.md
new file mode 100644
index 0000000..46d8226
--- /dev/null
+++ b/docs/tutorial/3-errors-and-randmoness.md
@@ -0,0 +1,3 @@
+# Tutorial 3: Errors and randomness
+
+to be done
\ No newline at end of file