diff --git a/README.md b/README.md
index f7a59e70..dae72911 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,13 @@
 
 Nix modules for darwin, `/etc/nixos/configuration.nix` for macOS.
 
+This project aims to bring the convenience of a declarative system approach to macOS.
+Nix-darwin is built up around [Nixpkgs](https://github.com/NixOS/nixpkgs), quite similar to [NixOs](https://nixos.org/).
+
 ## Install
 
+To install nix-darwin, a working installation of [Nix](https://github.com/NixOS/nix#installation) is required.
+
 ```bash
 nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A installer
 ./result/bin/darwin-installer
@@ -30,6 +35,9 @@ nix-channel --update darwin
 darwin-rebuild changelog
 ```
 
+> NOTE: If you are using Nix as a daemon service the channel for that will be owned by root.
+> Use `sudo -i nix-channel --update darwin` instead.
+
 ## Uninstalling
 
 There's also an uninstaller if you don't like the project and want to
@@ -40,6 +48,8 @@ nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A uninstalle
 ./result/bin/darwin-uninstaller
 ```
 
+> NOTE: This will also uninstall Nix alongside nix-darwin.
+
 ## Example configuration
 
 Configuration lives in `~/.nixpkgs/darwin-configuration.nix`. Check out
@@ -164,6 +174,16 @@ writing defaults...
 $
 ```
 
+## Documentation
+
+Reference documentation of all the options is available [here](https://lnl7.github.io/nix-darwin/manual/index.html#sec-options).--
+This can also be accessed locally using `man 5 configuration.nix`.
+
+`darwin-help` will open a HTML version of the manpage in the default browser.
+
+Furthermore there's `darwin-option` to introspect the settings of a system and its available options.
+> NOTE: `darwin-option` is only available to non-flake installations.
+
 ```
 $ darwin-option services.activate-system.enable
 Value:
@@ -179,12 +199,6 @@ Description:
 Whether to activate system at boot time.
 ```
 
-## Documentation
-
-Reference documentation of all the options is available here
-https://lnl7.github.io/nix-darwin/manual/index.html#sec-options.
-This can also be accessed locally using `man 5 configuration.nix`.
-
 There's also a small wiki https://github.com/LnL7/nix-darwin/wiki about
 specific topics, like macOS upgrades.
 
@@ -194,6 +208,9 @@ There are basic tests that run sanity checks for some of the modules,
 you can run them like this:
 
 ```bash
+# run all tests
+nix-build release.nix -A tests
+# or just a subset
 nix-build release.nix -A tests.environment-path
 ```
 
@@ -204,7 +221,7 @@ Don't hesitate to contribute modules or open an issue.
 
 To build your configuration with local changes you can run this. This
 flag can also be used to override darwin-config or nixpkgs, for more
-information on the `-I` flag look at the nix-build manpage.
+information on the `-I` flag look at the nix-build [manpage](https://nixos.org/manual/nix/stable/command-ref/nix-build.html).
 
 ```bash
 darwin-rebuild switch -I darwin=.