add some documentation about transformers

5 files changed, 58 insertions, 0 deletions

diff --git a/doc/index.rst b/doc/index.rst
index 9ce95b9..0b69ef1 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -12,6 +12,7 @@ Welcome to Fietsboek's documentation!
 
     administration
     developer
+    user
 
 .. toctree::
     :maxdepth: 1
diff --git a/doc/user.rst b/doc/user.rst
new file mode 100644
index 0000000..ab210dc
--- /dev/null
+++ b/doc/user.rst
@@ -0,0 +1,12 @@
+User Guide
+==========
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents
+
+    user/transformers
+
+This is the user guide for Fietsboek! In here, you can find information that
+might be interesting if you plan on sharing your tracks on a Fietsboek
+instance.
diff --git a/doc/user/images/fixed_elevation.png b/doc/user/images/fixed_elevation.png
new file mode 100644
index 0000000..10d34c7
--- /dev/null
+++ b/doc/user/images/fixed_elevation.png
diff --git a/doc/user/images/wrong_elevation.png b/doc/user/images/wrong_elevation.png
new file mode 100644
index 0000000..2e8557b
--- /dev/null
+++ b/doc/user/images/wrong_elevation.png
diff --git a/doc/user/transformers.rst b/doc/user/transformers.rst
new file mode 100644
index 0000000..c8ddf01
--- /dev/null
+++ b/doc/user/transformers.rst
@@ -0,0 +1,45 @@
+Transformers
+============
+
+Transformers are small (or big) transformations that are applied to your GPX
+track after it has been uploaded. This allows Fietsboek to provide some common,
+simple editing options, without users having to do that themselves.
+
+All transformers are optional and disabled by default. You can enable
+transformers when uploading a track on the bottom of the page. You can also
+enable transformers for already uploaded tracks in the editing view.
+
+.. note::
+
+    When enabling transformers for already existing tracks, your browser might
+    not show the changed track. Try force-refreshing (Crtl + F5) the page so
+    that it reloads the GPX from the server.
+
+In other applications, transformers are sometimes called "filters". That term
+however has many different meanings (like the filters on the "Browse" page),
+and as such, Fietsboek calls them transformers.
+
+Fix Null Elevation
+------------------
+
+The *fix null elevation* transformer removes points at the start and end of a
+track that have a "wrong" elevation. This helps to avoid issues when GPX
+trackers don't have elevation data yet and fill in 0, leading to wrong uphill
+calculations and wrong diagrams:
+
+.. image:: images/wrong_elevation.png
+    :width: 200
+    :alt: An elevation graph that starts at 0 and makes a jump to 165.
+
+Activating the transformer will produce the following track:
+
+.. image:: images/fixed_elevation.png
+    :width: 200
+    :alt: The same track, but with a fixed elevation graph that starts at 165.
+
+The transformer considers "wrong" elevation to be either points that have an
+elevation of 0, or points that have a slope of more than 100% to the next
+point.
+
+To fix those points, the transformer will find the first correct point, and
+copy its elevation to the wrong points.