Get first two parts of docs up to date and remove odcsim doc

11 files changed, 82 insertions, 44 deletions

diff --git a/README.md b/README.md
index 68feccc9..1bc866cf 100644
--- a/README.md
+++ b/README.md
@@ -27,18 +27,19 @@ This repository hosts the source code and development of the simulation componen
 ## Documentation
 Check out the [Getting Started](#getting-started) section for a quick
 overview.
-The documentation is located in the [docs/](docs/) directory and is divided as follows:
+The documentation is located in the [docs/](docs) directory and is divided as follows:
+1. [Introduction](docs/introduction.md)
 1. [Toolchain Setup](docs/setup.md)
 2. [Architecture Overview](docs/architecture.md)
-3. [Pre-built Models](docs/models.md)
-4. [Running a Model](docs/run.md)
-5. [Building Your Own Model](docs/build.md)
-6. [API Reference](https://atlarge-research.github.io/opendc-simulator) **(TODO maybe remove this until we have created this - see #36)**
+3. [Running an Experiment](docs/run.md)
+
+## Getting Started
+TODO
 
 ## Contributing
 ### Contributing Guide
 Read our [contributing guide](CONTRIBUTING.md) to learn about our
-development process, how  to propose bug fixes and improvements, and how
+development process, how to propose bug fixes and improvements, and how
 to build and test your changes to the project.
 
 ### License
diff --git a/docs/architecture.md b/docs/architecture.md
index a854bf6d..60ac3e0d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,8 +1,17 @@
-# 2. Architecture Overview
+# 3. Architecture Overview
+
+The OpenDC simulator has two main components: `odcsim`, a general framework for discrete event-based simulation, and `opendc` a collection of components using `odcsim` to simulate datacenters. We discuss both in turn!
+
+`TODO: Add a schematic general overview here.`
+
+## 3.1 `odcsim`
+
+
+## 3.2 `opendc`
 
 **TODO: What are the main components (odcsim-core, odcsim-engine, opendc-core, opendc-format, opendc-testkit, opendc-workflows, I assume)? Short description of each in a bullet list (or even a schema drawing, if you have the time). Why this division?**
 
 **TODO: One section per component, explaining what their responsibility is and what other modules they talk to. In what kind of scenarios do you as OpenDC developer need to touch/change them?**
 
 ---
-[< Previous](setup.md) | [Next >](models.md)
+[< Previous](setup.md) | [Next >](run.md)
diff --git a/docs/introduction.md b/docs/introduction.md
new file mode 100644
index 00000000..e6e3289d
--- /dev/null
+++ b/docs/introduction.md
@@ -0,0 +1,16 @@
+# 1. Introduction
+
+This repository hosts the source code and development of the simulation component of the [OpenDC](https://opendc.org) project. OpenDC is a simulation platform for cloud infrastructure, with the aim of making datacenter concepts and technology accessible to everyone. To learn more about OpenDC, have a look through our [vision paper](https://ieeexplore.ieee.org/document/8121623)!
+
+The simulator is one of the components of the OpenDC stack. It is responsible for modelling and simulation of datacenters and their components. This entails receiving environments and experiment configurations from up the stack, simulating these configurations, and reporting back results.
+
+The simulator is composed of two main components:
+- **[odcsim](/odcsim)**  
+  A framework for discrete event simulation.
+- **[opendc](/opendc)**  
+  A collection of models for simulating clouds, datacenters and their components, using the **odcsim** framework.
+
+In the remainder of this documentation, we walk you through a typical toolchain setup for amending OpenDC in your own way, explain the architecture of the system, and show you how to run your own experiments with the simulator.
+
+---
+[Next >](setup.md)
diff --git a/docs/models.md b/docs/models.md
deleted file mode 100644
index fab8cdcf..00000000
--- a/docs/models.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# 3. Pre-built Models
-
-**TODO: Introduction: we have a library of pre-built models to make things easier for you, here we present them etc.**
-
-**Per model in the architecture (corresponding with the architecture document), give the list of models we include out of the box. Explain what it does (and if applicable, what it doesn't do).**
-
----
-[< Previous](architecture.md) | [Next >](models.md)
diff --git a/docs/run.md b/docs/run.md
index d3143d96..1eadfedf 100644
--- a/docs/run.md
+++ b/docs/run.md
@@ -1,6 +1,6 @@
-# 4. Running a Model
+# 4. Running an Experiment
 
-**TODO: Not sure yet what's useful to include here. Maybe give an example of how to run one of the pre-builts?**
+**TODO: What did we do for SC18?**
 
 ---
-[< Previous](models.md) | [Next >](build.md)
+[< Previous](architecture.md)
diff --git a/docs/setup.md b/docs/setup.md
index f7ab9f12..0c5d412a 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -1,18 +1,52 @@
-# 1. Toolchain Setup
+# 2. Toolchain Setup
 
-**TODO: Introduction: What basic libraries/language(s) do we use, with links to their respective sites. What tool do we recommend (IDEA probably). Explain that we will now give two alternative ways (IDEA and shell).**
+The OpenDC simulator is built using the [Kotlin](https://kotlinlang.org/) language. This is a JVM-based language that should appear familiar to programmers knowledgeable in Java or Scala. For a short interactive introduction to Kotlin, the [Learn Kotlin By Example](https://play.kotlinlang.org/byExample/overview) docs are a great place to start.
 
-## Installing Java
+For the build and dependency toolchain, we use [Gradle](https://gradle.org/). You will likely not need to change the Gradle build configurations of components, but you will use Gradle to execute builds and tests on the codebase.
 
-**TODO: Explain which version they need and where they can get it.**
+Follow the steps below to get it all set up!
 
-## Setup With IntelliJ IDEA
+## 2.1 Installing Java
 
-**TODO: Take the user from not having IDEA to having the opendc-simulator codebase open in the environment. Finish with running a test to see if it works.**
+Kotlin requires a Java installation of version 8 or higher. Make sure to install the [JDK](https://www.oracle.com/technetwork/java/javase/downloads/index.html), not only the JRE (the JDK also includes a JRE).
 
-## Setup With Shell
+## 2.2 Building and Developing
 
-**TODO: Take the user from not having the codebase to having it and having all dependencies fetched with Gradle. This will likely need separate instructions for Windows and for Linux/MacOS. Advise maybe VS Code as editor to view things after installation. Finish with running a test to see if it works.**
+With Java installed, we're ready to set up the development environment on your machine. You can either use a visual IDE or work from a command line shell. We outline both approaches below, feel free to choose which you are most comfortable with. If in doubt which one to choose, we suggest going with the first one.
+
+## 2.2.1 Setup With IntelliJ IDEA
+
+We suggest using [IntelliJ IDEA](https://www.jetbrains.com/idea/) as development environment. Once you have installed any version of this IDE on your machine, choose "Get from Version Control" in the new project dialogue. Enter `https://atlarge.ewi.tudelft.nl/gitlab/opendc/opendc-simulator` as URL and submit your credentials when asked. Open the project once it's ready fetching the codebase, and let it set up with the defaults (IntelliJ will recognize that this is a Gradle codebase).
+
+You will now be prompted in a dialogue to enable auto-import for Gradle, which we suggest you do. Wait for any progress bars in the lower bar to disappear and then look for the Gradle context menu on the right hand side. In it, go to `opendc-simulator > Tasks > verification > test`. This will build the codebase and run checks to verify that tests pass. If you get a `BUILD SUCCESSFUL` message, you're ready to go to the [next section](architecture.md)!
+
+## 2.2.2 Setup With Command Line
+
+First, clone the repository with the following command:
+
+```shell script
+git clone https://atlarge.ewi.tudelft.nl/gitlab/opendc/opendc-simulator
+```
+
+And enter the directory:
+
+```shell script
+cd opendc-simulator
+```
+
+If on Windows, run the batch file included in the root, as follows:
+
+```commandline
+gradlew.bat test
+```
+
+If on Linux/macOS, run the shell script included in the root, as follows:
+
+```shell script
+./gradlew test
+```
+
+If the build is successful, you are ready to go to the next section!
 
 ---
-[Next >](architecture.md)
+[< Previous](introduction.md) | [Next >](architecture.md)
diff --git a/odcsim/README.md b/odcsim/README.md
index e5dcc319..b0040cab 100644
--- a/odcsim/README.md
+++ b/odcsim/README.md
@@ -14,18 +14,10 @@ and the interactions between these actors
 ([Actor model](https://en.wikipedia.org/wiki/Actor_model)), using
 an API similar to [Akka](https://doc.akka.io/docs/akka/current/index.html).
 
-## Documentation
-Check out the [Getting Started](#getting-started) section for a quick
-overview.
-The documentation is located in the [docs/](docs/) directory and is divided as follows:
-* [Main Concepts](docs/concepts.md)
-* [Building a Model](docs/build.md)
-* [Running a Model](docs/run.md)
-* [API Reference](https://atlarge-research.github.io/opendc-simulator)
-* [Contributing Guide](../CONTRIBUTING.md)
-
 ## Getting Started
 
+The instructions below are meant for when you would like to use `odcsim` separately from `opendc`. If you simply want to use the simulator, you do not need to follow them, please refer to the [main README](../README.md) for instructions.
+
 ### Installation
 Please add the required packages as dependency in your project.
 Releases are available in the [Maven Central Repository](https://search.maven.org/).
diff --git a/odcsim/docs/build.md b/odcsim/docs/build.md
deleted file mode 100644
index 21983355..00000000
--- a/odcsim/docs/build.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# 5. Building Your Own Model
-
-**TODO: What goes into building a model? Where do you start? Can be quite technical (what gradle scripts do I need to make, what directory structure, ...), maybe center around a simple example scenario?**
-
----
-[< Previous](run.md)
diff --git a/odcsim/docs/concepts.md b/odcsim/docs/concepts.md
deleted file mode 100644
index e69de29b..00000000
--- a/odcsim/docs/concepts.md
+++ /dev/null
diff --git a/odcsim/docs/models.md b/odcsim/docs/models.md
deleted file mode 100644
index e69de29b..00000000
--- a/odcsim/docs/models.md
+++ /dev/null
diff --git a/odcsim/docs/run.md b/odcsim/docs/run.md
deleted file mode 100644
index e69de29b..00000000
--- a/odcsim/docs/run.md
+++ /dev/null