From e0a2270c3f6fb951bbb0b5f0625779d11f56f8c6 Mon Sep 17 00:00:00 2001
From: Marcus Messer <marcus@marcusm.co.uk>
Date: Mon, 27 Apr 2026 13:37:53 +0100
Subject: [PATCH] Updated user docs

---
 app/docs/user.md | 58 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 3 deletions(-)

diff --git a/app/docs/user.md b/app/docs/user.md
index 874136b..438113f 100644
--- a/app/docs/user.md
+++ b/app/docs/user.md
@@ -1,7 +1,59 @@
-# IsSimilar 
+# IsSimilar
 
-Use this evaluation function to check if the student's reponse is within a tolerance range defined in `params`. Works exactly like the [numpy.isclose](https://numpy.org/doc/stable/reference/generated/numpy.isclose.html#numpy.isclose) function. Valid params include `atol` and `rtol` (absolute and relative tolerances) which can be used in combination, or alone.
+Use this evaluation function to check if a student's response is within a tolerance range of the correct answer. Works like the [numpy.isclose](https://numpy.org/doc/stable/reference/generated/numpy.isclose.html#numpy.isclose) function.
+
+A response is accepted if:
+
+```
+|response - answer| ≤ atol + rtol × |answer|
+```
+
+The left-hand side is the absolute difference between the student's response and the correct answer. The right-hand side is the total allowed difference, made up of a fixed part (`atol`) and a part that scales with the size of the answer (`rtol × |answer|`). A response is marked correct whenever the actual difference does not exceed the allowed difference.
+
+## Parameters
+
+Both parameters default to `0` (exact match required) and can be used individually or together.
+
+### `atol` — Absolute tolerance
+
+Specifies a fixed margin around the answer, regardless of its magnitude. Use this when you know the acceptable error in the same units as the answer.
+
+### `rtol` — Relative tolerance
+
+Specifies an acceptable error as a fraction of the answer's magnitude. Use this when the answer is very large or very small and a percentage-based margin makes more sense than a fixed one.
+
+## Examples
+
+### Exact match (default)
+
+No params needed. The student must enter exactly `42` (floating-point precision is handled automatically).
+
+### Absolute tolerance
+
+```json
+{ "atol": 0.05 }
+```
+
+With answer `9.81`, accepts any response in the range **9.76 – 9.86**. Good for physical measurements where the acceptable error is known in the same units.
+
+### Relative tolerance
+
+```json
+{ "rtol": 0.01 }
+```
+
+With answer `6.674e-11`, accepts any response within **1%** of the answer. Good for very large or very small values where a fixed margin would be impractical.
+
+### Combined tolerances
+
+```json
+{ "atol": 0.01, "rtol": 0.005 }
+```
+
+Both tolerances contribute: with answer `9.81`, the allowed difference is `0.01 + 0.005 × 9.81 ≈ 0.059`. Useful when you want a minimum floor (`atol`) plus a proportional allowance (`rtol`).
+
+## Notes
 
 **Note:** If the answer is not a number, all responses will generate an error.
 
-**Note:** If the response is not a number, a feedback message asking the user to submit a number will be returned.
\ No newline at end of file
+**Note:** If the response is not a number, a feedback message asking the student to submit a number will be returned.