diff --git a/README.md b/README.md
index 1d7b7ada..03462cdc 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,69 @@ this repository nxios configurations of the digital malobeo infrastructure. it s
 
 ## creating a new host
 
+### setting up filesystem
 currently nixos offers no declarative way of setting up filesystems and partitions. that means this has to be done manually for every new host. [to make it as easy as possible we can use this guide to setup an encrypted zfs filesystem](https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/Root%20on%20ZFS.html)
 
-we could create a shell script out of that
+*we could create a shell script out of that*
+
+### deploying configuration
+
+``` shell
+TODO
+```
+
+## development
+
+### requirements
+we use flake based configurations for our hosts. if you want to build configurations on you own machine you have to enable flakes first by adding the following to your *configuration.nix* or *nix.conf*
+``` nix
+nix.extraOptions = ''
+  experimental-features = nix-command flakes
+'';
+```
+
+More information about flakes can be found [here](https://nixos.wiki/wiki/Flakes)
+
+### dev shell
+a development shell with the correct environment can be created by running ```nix develop ```
+
+If you're using direnv you can add flake support by following those steps: [link](https://nixos.wiki/wiki/Flakes#Direnv_integration)
+
+### build a configuration
+
+to build a configuration run the following command (replace ```<hostname>``` with the actual hostname):
+
+``` shell
+nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel
+```
+
+### run a configuration as vm
+
+to run a vm we have to build it first using the following command (replace ```<hostname>``` with the actual hostname):
+
+``` shell
+nix build .#nixosConfigurations.<hostname>.config.system.build.vm
+```
+
+afterwards run the following command to start the vm:
+
+``` shell
+TODO
+```
+
+### documentation
+
+for documentation we currently just use README.md files.
+
+the devshell provides the python package ['grip'](https://github.com/joeyespo/grip) which can be used to preview different README.md files in the browser.
+the usage is simple, just run ```grip``` in the same folder as the README.md you wanna preview. then open your browser at ```http://localhost:6419 ```.
+
+
+### ideas...
+* host a local wiki with public available information about the space, for example:
+  * how to use coffe machine
+  * how to turn on/off electricity
+  * ...
+* host some pad (codimd aka hedgedoc)
+* some network fileshare for storing the movies and streaming them within the network
+