diff --git a/CHANGELOG.md b/CHANGELOG.md
index a59c1732cb..8a3a11fc69 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,12 +1,13 @@
 v 2019.2
 Changes in this release:
-- various bugfixes (#1046, #968, #1045)
+- Various bugfixes (#1046, #968, #1045)
 - Migration from mongodb to postgres
 - added metering using pyformance
-- added influxdb reporter for protocol endpoint metrics
+- Added influxdb reporter for protocol endpoint metrics
 - Remove the configuration option agent-run-at-start (#1055)
 - Add project id and environment id as optional parameters to API call (#1001)
 - Fixed an issue which cleared the environment on remote python 2 interpreters
+- Documentation updates and improvements (#905)
 
 v 2019.1 (2019-03-06)
 Changes in this release:
diff --git a/docs/architecture.rst b/docs/architecture.rst
index 3f9c87208b..30637a0543 100644
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@@ -1,3 +1,5 @@
+.. _arch:
+
 Architecture
 ============
 
@@ -60,6 +62,27 @@ In a push to server model, the server is deployed on an external machine, but mo
 machine. This gives faster feedback to developers, but makes the compilation less reproducible. It also complicates
 collaboration.
 
+Both the developer machine and the server need to have Inmanta installed. To compile and export models to the server from the
+developer machine a `.inmanta` file is required in the project directory (where you find the main.cf and the project.yaml file)
+to connect the compiler with the server.
+
+Create a `.inmanta` file in the project directory and include the following configuration::
+
+    [config]
+    environment=$ENV_ID
+
+    [compiler_rest_transport]
+    host=$SERVER_ADDRESS
+    port=$SERVER_PORT
+
+Replace ``$ENV_ID``, ``$SERVER_ADDRESS`` and ``$SERVER_PORT`` with the correct values (See :inmanta.config:group:`compiler_rest_transport`
+for more details when using ssl and or auth, :inmanta.config:option:`config.environment` explains the environment setting). A best
+practice is to not add the .inmanta to the git repository. Because different developer may use different orchestration servers.
+
+ * ``inmanta compile`` compiles the current project but does not upload the result to the orchestration server.
+ * ``inmanta export`` compiles and uploads the current project to the orchestration server. Depending on the environment settings the server will release and deploy the model or it becomes available in the `new` state.
+ * ``inmanta export -d`` compiles, uploads and releases the current project. The result will start deploying immediately.
+
 
 Autonomous server
 *****************