diff --git a/docs/notebooks.rst b/docs/notebooks.rst
index ff40b86..44fd5bf 100644
--- a/docs/notebooks.rst
+++ b/docs/notebooks.rst
@@ -5,4 +5,6 @@ Notebooks
 
     Introducing Jupyter Notebooks <notebooks/intro_notebook>
     Adler phasecurve models <notebooks/adler_phasecurve_example>
-    Adler plotting example <notebooks/plotting_utilities_example>
\ No newline at end of file
+    Adler plotting example <notebooks/plotting_utilities_example>
+    Adler outlier detection <notebooks/outlier_detection_example>
+    Adler colour measurement <notebooks/colour_functions_example>
\ No newline at end of file
diff --git a/docs/notebooks/colour_functions_example.ipynb b/docs/notebooks/colour_functions_example.ipynb
index 0d197ce..c94e62d 100644
--- a/docs/notebooks/colour_functions_example.ipynb
+++ b/docs/notebooks/colour_functions_example.ipynb
@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "id": "d3190549",
+   "id": "6ebe3e22",
    "metadata": {},
    "source": [
     "# Adler running colour measurement\n",
@@ -146,6 +146,16 @@
     "adler_data.get_phase_parameters_in_filter(\"g\", \"HG12_Pen16\").__dict__"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "e07e86a8",
+   "metadata": {},
+   "source": [
+    "# Get determine the apparitions (periods of observability) of the object\n",
+    "Get the boundary times for each apparation of the object in the survey using the Adler helper function `apparition_gap_finder`.\n",
+    "In this example we will just look at changes in colour for a single apparition"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -153,8 +163,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# get the boundary times for each apparation of the object in the survey\n",
-    "# in this example we will just look at changes in colour for a single apparition\n",
+    "# combine all measurements in r and g into one dataframe as apparitions are filter independent\n",
     "df_obs_all = pd.DataFrame()\n",
     "for filt in [\"r\", \"g\"]:\n",
     "    obs = planetoid.observations_in_filter(filt)\n",
@@ -162,6 +171,7 @@
     "    df_obs_all = pd.concat([df_obs_all, _df_obs])\n",
     "df_obs_all = df_obs_all.sort_values(\"midPointMjdTai\")\n",
     "\n",
+    "# get the boundary times\n",
     "t_app = apparition_gap_finder(np.array(df_obs_all[\"midPointMjdTai\"]))\n",
     "print(t_app)"
    ]
@@ -176,7 +186,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "5fd261a3",
+   "id": "08f25eb8",
    "metadata": {},
    "source": [
     "Here we simulate observations coming night-by-night and the calculation of a g-r colour for the object\n"
@@ -298,7 +308,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "7f505a7e",
+   "id": "fae0b512",
    "metadata": {},
    "source": [
     "Now we can plot how the colour changes as a function of time"
@@ -344,7 +354,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "620fe556",
+   "id": "2aad6ee0",
    "metadata": {},
    "source": [
     "These colours can then be run through the previously written outlier detection functions.\n",
diff --git a/docs/notebooks/outlier_detection_example.ipynb b/docs/notebooks/outlier_detection_example.ipynb
index edc06fb..285e280 100644
--- a/docs/notebooks/outlier_detection_example.ipynb
+++ b/docs/notebooks/outlier_detection_example.ipynb
@@ -1,5 +1,14 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "5b6823e7",
+   "metadata": {},
+   "source": [
+    "# Adler outlier detection\n",
+    "This notebook demonstrates some of the functions provide by Adler to assist with simple outlier detection"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -60,7 +69,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# calculate data - model residuals\n",
+    "# calculate data minus model residuals\n",
     "res = obs_r.reduced_mag - pc.ReducedMag(obs_r.phaseAngle * u.degree).value"
    ]
   },
@@ -151,13 +160,12 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "13e25b85",
+   "cell_type": "markdown",
+   "id": "4318568a",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "# return a list of flags for outlying objects"
+    "# return a list of flags for outlying objects\n",
+    "The Adler `utils.sigma_clip` function is a wrapper for `astropy.stats.sigma_clip`. We do this in order to return just the clip mask, and also to make it easier to call a \"zero\" central function."
    ]
   },
   {
@@ -255,13 +263,11 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "8c935b03",
+   "cell_type": "markdown",
+   "id": "e66bfbee",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "# NB that for phase curve models, residuals can be much larger than the photometric uncertainty!"
+    "NB that for phase curve models, residuals can be much larger than the photometric uncertainty!"
    ]
   },
   {
@@ -275,9 +281,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "adler-dev",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
-   "name": "adler-dev"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -289,7 +295,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.14"
+   "version": "3.9.19"
   }
  },
  "nbformat": 4,