diff --git a/docs/getting_started.rst b/docs/getting_started.rst
index b0fa1d59e341ff7b096586df8a9cd5092e824561..d95a8accfa49fc98fe1e6a46da1cb5a85a9ebc84 100644
--- a/docs/getting_started.rst
+++ b/docs/getting_started.rst
@@ -12,7 +12,7 @@ Step 1: From root aanet files to h5 aanet files
 Convert offline files (aka aanet files) from root format to h5 format using
 the 'h5extract' command of km3pipe like so::
 
-    h5extract filename.root
+    h5extract aanet_file.root
 
 .. note::
     This has to be done only once for each file. Check if somebody did this
@@ -23,8 +23,14 @@ the 'h5extract' command of km3pipe like so::
 Step 2: From h5 aanet files to h5 DL files
 ------------------------------------------
 Produce DL h5 files from the aanet h5 files using OrcaSong.
-You can either produce images or graphs. See :ref:`orcasong_page` for
-instructions on how to do this.
+You can either produce images or graphs.
+If you have an orcasong config file, you can use it via the command line like this::
+
+    orcasong run aanet_file.h5 orcasong_config.toml --detx_file detector.detx
+
+
+Alternatively, you can use the python frontend of orcasong.
+See :ref:`orcasong_page` for instructions on how to do this.
 
 The resulting DL h5 files can already be used as input for networks!
 
diff --git a/docs/orcasong.rst b/docs/orcasong.rst
index 659e46ca88d0300b392d15dff667b7d3abc1e306..cbd9139c13428a50171ee3d57ff688619e7b194b 100644
--- a/docs/orcasong.rst
+++ b/docs/orcasong.rst
@@ -3,7 +3,7 @@
 Producing DL h5 files from aanet h5 files
 =========================================
 
-Describes how to use OrcaSong to produce h5 files for Deep Learning
+Describes how to use OrcaSong in python to produce h5 files for Deep Learning
 from aanet h5 files. These files can contain either images (for convolutional
 networks), or graphs (for Graph networks).
 
diff --git a/docs/tools.rst b/docs/tools.rst
index 022f9809cab5d1ec0ad1467ebdbb54699bd9caab..1f0ac81698b5a707cd3cbdbd613402559cf515f0 100644
--- a/docs/tools.rst
+++ b/docs/tools.rst
@@ -37,7 +37,7 @@ km3pipe. The input can also be a txt file like from make_data_split.
 
 Can be used via the commandline like so::
 
-    concatenate --help
+    orcasong concatenate --help
 
 or import as:
 
@@ -58,7 +58,7 @@ Shuffle an h5 file using km3pipe.
 
 Can be used via the commandline like so::
 
-    h5shuffle --help
+    orcasong h5shuffle --help
 
 or import function for general postprocessing:
 
@@ -69,4 +69,7 @@ or import function for general postprocessing:
     postproc_file(output_filepath_concat)
 
 
-Theres also a faster (beta) version available called h5shuffle2.
+Theres also a faster (beta) version available called h5shuffle2::
+
+    orcasong h5shuffle2 --help
+
diff --git a/examples/orcasong_example.toml b/examples/orcasong_example.toml
index 5ab2719ebb2f4939acc1231858363b836bc6fb8c..0e580f173f4d5dfa61ddb8781d2bf0018ab97d6c 100644
--- a/examples/orcasong_example.toml
+++ b/examples/orcasong_example.toml
@@ -1,3 +1,6 @@
+# This is an example config for running orcasong. It's not intended
+# to be used for actual large-scale productions.
+
 # the mode to run orcasong in; either 'graph' or 'image'
 mode="graph"
 # arguments for FileGraph or FileBinner (see orcasong.core)
@@ -6,8 +9,8 @@ time_window = [-100, 5000]
 # can also give the arguments of orcasong.core.BaseProcessor,
 # which are shared between modes
 chunksize=16
-# built-in extractor function to use
+# built-in extractor function to use (see orcasong.from_toml.EXTRACTORS)
 extractor = "neutrino_mc"
 
 [extractor_config]
-# optional arguments for the extractor function can go here. None in this case.
+# arguments for setting up the extractor function can go here. None in this case.