diff --git a/docs/source/.~how_it_works.rst b/docs/source/.~how_it_works.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/docs/source/how_it_works.rst b/docs/source/how_it_works.rst
index fe1f3640d3398244e7c8f8acba14d32adc0b749c..9534ee367c2665dc3862acb28678c6896c71c73f 100644
--- a/docs/source/how_it_works.rst
+++ b/docs/source/how_it_works.rst
@@ -1,3 +1,5 @@
+.. _how_it_works:
+
 How it Works
 ============
 
@@ -7,11 +9,11 @@ to expose Jupyter_ notebooks to a command line interface.
 Additionally, it leverages the DESY/XFEL Maxwell cluster to run these jobs in parallel
 via SLURM_.
 
-Here is a list of :ref:`_available_notebooks`_.
+Here is a list of :ref:`available_notebooks`.
 
-If you would like to integrate additional notebooks please see the :ref:`development_workflow`_.
+If you would like to integrate additional notebooks please see the :ref:`development_workflow`.
 
 .. _nbparameterise: https://github.com/takluyver/nbparameterise
 .. _nbconver: https://github.com/jupyter/nbconvert
 .. _jupyter: http://jupyter.org/
-.. _SLURM: https://slurm.schedmd.com
\ No newline at end of file
+.. _SLURM: https://slurm.schedmd.com
diff --git a/docs/source/workflow.rst b/docs/source/workflow.rst
index 06957509973ff54e69793b37b101b65c5ecee03c..d619f0533b2c93b9ae86b15e13bcf289cc4c2728 100644
--- a/docs/source/workflow.rst
+++ b/docs/source/workflow.rst
@@ -150,22 +150,21 @@ The following table contains a list of suggested names for certain parameters, a
 to stay consistent amongst all notebooks.
 
 
-.. table:: Suggested naming of parameters
-
-    Parameter name   To be used for                                                  Special purpose
-    ---------------- --------------------------------------------------------------- --------------------------
-    in_folder        the input path data resides in, usually without a run number
-    out_folder       path to write data out to, usually without a run number         reports can be placed here
-    run(s)           which XFEL DAQ runs to use, often ranges are allowed
-    modules          refers to the modules of a segmented detector, ranges often ok.
-    sequences        sequence files for the XFEL DAQ system, ranges are often ok.
-    cluster_profile  name of the cluster profile for ipcluster                       fixed name
-    local_input      read calibration constant from file, not database
-    local_output     write calibration constant from file, not database
-    db_input         read calibration constant from database, not file
-    db_output        write calibration constant from database, not file
-    cal_db_interface the calibration database host in form of "tcp://host:port"
-
+================ =============================================================== ==========================
+Parameter name   To be used for                                                  Special purpose
+---------------- --------------------------------------------------------------- --------------------------
+in_folder        the input path data resides in, usually without a run number
+out_folder       path to write data out to, usually without a run number         reports can be placed here
+run(s)           which XFEL DAQ runs to use, often ranges are allowed
+modules          refers to the modules of a segmented detector, ranges often ok.
+sequences        sequence files for the XFEL DAQ system, ranges are often ok.
+cluster_profile  name of the cluster profile for ipcluster                       fixed name
+local_input      read calibration constant from file, not database
+local_output     write calibration constant from file, not database
+db_input         read calibration constant from database, not file
+db_output        write calibration constant from database, not file
+cal_db_interface the calibration database host in form of "tcp://host:port"
+================ =============================================================== ==========================
 
 
 Best Coding Practices