diff --git a/README.md b/README.md
index 832f0360..e55a666e 100644
--- a/README.md
+++ b/README.md
@@ -60,8 +60,8 @@ using the debugger alone? For further refinements of the implementation see
 [`frontend{2,3,4}.go`](src/sut/register) and see if you can figure out why they
 do or don't work as well.
 
-More about `nix` can be found [here](doc/nix.md), including why it's preferbable
-to `docker` and how to overcome some weak points of `nix-shell`.
+More about `nix` can be found [here](doc/nix.md), including a recommended
+developer workflow and why it's preferbable to `docker`.
 
 ### How it works on a higher-level
 
diff --git a/doc/nix.md b/doc/nix.md
index 95741ddd..e4719ee9 100644
--- a/doc/nix.md
+++ b/doc/nix.md
@@ -1,5 +1,36 @@
 ### Nix
 
+#### Development workflow
+
+Once you got `nix` installed, it should be a matter of typing
+`nix-shell` at the root of the repo to get the development environment
+setup as well as access to all binaries, in particular the `detsys`
+command-line interface tool.
+
+If you change some detsys component, you can exit the`nix-shell` and
+reenter it again, this should only rebuild the change component and any
+dependencies of it.
+
+If you find `nix-shell` rebuilding more than necessary, then you can
+also try to run `nix-env --install --file default.nix` from within the
+directory of the component that gets unnecessarily rebuilt. This is the
+`nix` equivalent of `make install`, you can also do `nix-build` from
+within the directory of a component to see if the `default.nix` builds
+(equivalent to `make`).
+
+If you want to more iteratively develop your component, you can also use
+whatever language specific compiler or build tool the component uses.
+Note however that `detsys` will use whatever binary it finds first in
+your `PATH`, which could be old versions installed by `nix-env`. All
+`detsys` components come with a `--version` flag and the `detsys`
+command-line interface tool also has a `versions` subcommand to help you
+ensure that you are using the intended versions of the components.
+
+This entering `nix-shell`, leaving and reentering it again is obviously
+annoying. `lorri` is beefed up version of `nix-shell` that is supposed
+to address some of these shortcomings, but we've still not figured out
+how to use it.
+
 #### Why `nix` over `docker`?
 
 * Just `cd` into the directory and it automatically makes all your tools
@@ -62,6 +93,9 @@ purpose.
 
 #### How to setup `nix` for a software component
 
+TODO(stevan): the following is slightly outdated, we currently have a
+single `niv init` at the top-level which all components use.
+
 ```bash
 cd $component
 niv init