diff --git a/dist/tools/zep_dispatch/README.md b/dist/tools/zep_dispatch/README.md
index 6d862a17c2..92b632a727 100644
--- a/dist/tools/zep_dispatch/README.md
+++ b/dist/tools/zep_dispatch/README.md
@@ -144,3 +144,20 @@ instance [0 | Iface: 7 | mop: 2 | ocp: 0 | mhri: 256 | mri 0]
 ```
 
 This should also be visible in Foren6.
+
+Topology generation
+-------------------
+
+To generate a random topology use the `topogen.sh` script.
+This will randomly distribute *N* nodes on on a *W* × *H* map.
+Each node has a radio range *R* ± *V* where *V* is a random variance that can also be set to 0.
+
+The further away a node is from a sending node, the higher the packet loss probability.
+Nodes outside the sending radius have a zero probability of receiving a packet.
+
+If you have `gnuplot` installed this will also generate a plot of the resulting node distribution:
+
+![example topology](https://gist.githubusercontent.com/benpicco/6fd6f7c79a30cbbc41c3a65e53ed3682/raw/33afb859b65d949238129096858d14e2319fb5fb/network.topo.svg)
+
+A light color means that a node only has a one-way connection to the network, gray means a node is
+entirely isolated.
diff --git a/dist/tools/zep_dispatch/topogen.sh b/dist/tools/zep_dispatch/topogen.sh
index 733bfbdc2e..db19059282 100755
--- a/dist/tools/zep_dispatch/topogen.sh
+++ b/dist/tools/zep_dispatch/topogen.sh
@@ -16,11 +16,11 @@ else
     CRESET=
 fi
 
-WIDTH=100
-HEIGHT=100
-RANGE=30
-VARIANCE=15
-NUM=10
+WIDTH=100	# X dimension of the simulated world
+HEIGHT=100	# Y dimension of the simulated world
+RANGE=30	# base node radio range
+VARIANCE=15	# random offset to radio range
+NUM=10		# number of nodes
 
 echo "writing to $FILE"