From 97a93cceebe020deae315560f9e186dfcb0ba92e Mon Sep 17 00:00:00 2001
From: xengineering <me@xengineering.eu>
Date: Mon, 8 Jan 2024 21:37:16 +0100
Subject: WIP: doc: Add API structure from developer perspective

---
 doc/diagrams/device-semver-developer.svg | 239 +++++++++++++++++++++++++++++++
 doc/diagrams/device-semver-user.svg      | 223 ++++++++++++++++++++++++++++
 doc/diagrams/device-semver.svg           | 223 ----------------------------
 doc/doc.mk                               |   2 +-
 doc/documentation.tex                    |  15 +-
 5 files changed, 474 insertions(+), 228 deletions(-)
 create mode 100644 doc/diagrams/device-semver-developer.svg
 create mode 100644 doc/diagrams/device-semver-user.svg
 delete mode 100644 doc/diagrams/device-semver.svg

diff --git a/doc/diagrams/device-semver-developer.svg b/doc/diagrams/device-semver-developer.svg
new file mode 100644
index 0000000..fd5b38a
--- /dev/null
+++ b/doc/diagrams/device-semver-developer.svg
@@ -0,0 +1,239 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="150mm"
+   height="55mm"
+   viewBox="0 0 150 55"
+   version="1.1"
+   id="svg1"
+   inkscape:version="1.3.2 (091e20ef0f, 2023-11-25, custom)"
+   sodipodi:docname="device-semver-developer.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm"
+     showgrid="true"
+     inkscape:zoom="2.0588333"
+     inkscape:cx="285.8415"
+     inkscape:cy="67.999678"
+     inkscape:window-width="1916"
+     inkscape:window-height="1028"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="layer1">
+    <inkscape:grid
+       id="grid1"
+       units="mm"
+       originx="0"
+       originy="0"
+       spacingx="0.99999999"
+       spacingy="0.99999999"
+       empcolor="#0099e5"
+       empopacity="0.30196078"
+       color="#0099e5"
+       opacity="0.14901961"
+       empspacing="5"
+       dotted="false"
+       gridanglex="30"
+       gridanglez="30"
+       visible="true" />
+  </sodipodi:namedview>
+  <defs
+     id="defs1" />
+  <g
+     inkscape:label="Ebene 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="35.146614"
+       y="34.455166"
+       id="text1"><tspan
+         sodipodi:role="line"
+         id="tspan1"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="35.146614"
+         y="34.455166">Mechanical</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="35.146614"
+         y="37.277397"
+         id="tspan2">parts</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1"
+       width="20"
+       height="10"
+       x="25"
+       y="29.999998" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="60.014114"
+       y="34.322666"
+       id="text1-3"><tspan
+         sodipodi:role="line"
+         id="tspan1-5"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="60.014114"
+         y="34.322666">Electronic</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="60.014114"
+         y="37.144897"
+         id="tspan2-6">parts</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2"
+       width="20"
+       height="10"
+       x="50"
+       y="30" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="34.950615"
+       y="21.058338"
+       id="text1-3-0"><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="34.950615"
+         y="21.058338"
+         id="tspan2-6-3">Firmware</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2-6"
+       width="20"
+       height="10"
+       x="25"
+       y="15" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="59.950615"
+       y="21.058338"
+       id="text1-3-0-1"><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="59.950615"
+         y="21.058338"
+         id="tspan2-6-3-8">Software</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2-6-7"
+       width="20"
+       height="10"
+       x="50"
+       y="15" />
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none"
+       id="rect3"
+       width="55"
+       height="35"
+       x="20"
+       y="10" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="20.802444"
+       y="43.971779"
+       id="text3"><tspan
+         sodipodi:role="line"
+         id="tspan3"
+         style="stroke-width:0.264583"
+         x="20.802444"
+         y="43.971779">Device</tspan></text>
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5"
+       width="22"
+       height="12"
+       x="24"
+       y="13.999999" />
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5-5"
+       width="22"
+       height="12"
+       x="49"
+       y="13.999999" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 119.875,29.875 V 21.884426"
+       id="path9"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 119.875,29.874999 3,5"
+       id="path10" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 119.875,29.874999 -3,5"
+       id="path11" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 116.875,24.875001 h 6"
+       id="path12" />
+    <ellipse
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-dashoffset:0"
+       id="path13"
+       cx="119.875"
+       cy="19.384426"
+       rx="2.531951"
+       ry="2.5" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="112.69416"
+       y="38.57132"
+       id="text13"><tspan
+         sodipodi:role="line"
+         id="tspan13"
+         style="stroke-width:0.264583"
+         x="112.69416"
+         y="38.57132">Developer</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="100.84268"
+       y="46.773823"
+       id="text14"><tspan
+         sodipodi:role="line"
+         id="tspan14"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="100.84268"
+         y="46.773823">multipe 'API's as defined</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="100.84268"
+         y="49.596054"
+         id="tspan15">by Semantic Versioning</tspan></text>
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5-2"
+       width="22"
+       height="12"
+       x="24"
+       y="28.999998" />
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5-7"
+       width="22"
+       height="12"
+       x="49"
+       y="28.999998" />
+  </g>
+</svg>
diff --git a/doc/diagrams/device-semver-user.svg b/doc/diagrams/device-semver-user.svg
new file mode 100644
index 0000000..8a68362
--- /dev/null
+++ b/doc/diagrams/device-semver-user.svg
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="150mm"
+   height="55mm"
+   viewBox="0 0 150 55"
+   version="1.1"
+   id="svg1"
+   inkscape:version="1.3.2 (091e20ef0f, 2023-11-25, custom)"
+   sodipodi:docname="device-semver.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm"
+     showgrid="true"
+     inkscape:zoom="1.9638901"
+     inkscape:cx="240.08472"
+     inkscape:cy="127.80756"
+     inkscape:window-width="1916"
+     inkscape:window-height="1028"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="layer1">
+    <inkscape:grid
+       id="grid1"
+       units="mm"
+       originx="0"
+       originy="0"
+       spacingx="0.99999999"
+       spacingy="0.99999999"
+       empcolor="#0099e5"
+       empopacity="0.30196078"
+       color="#0099e5"
+       opacity="0.14901961"
+       empspacing="5"
+       dotted="false"
+       gridanglex="30"
+       gridanglez="30"
+       visible="true" />
+  </sodipodi:namedview>
+  <defs
+     id="defs1" />
+  <g
+     inkscape:label="Ebene 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="35.146614"
+       y="34.455166"
+       id="text1"><tspan
+         sodipodi:role="line"
+         id="tspan1"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="35.146614"
+         y="34.455166">Mechanical</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="35.146614"
+         y="37.277397"
+         id="tspan2">parts</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1"
+       width="20"
+       height="10"
+       x="25.1325"
+       y="30.1325" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="60.014114"
+       y="34.322666"
+       id="text1-3"><tspan
+         sodipodi:role="line"
+         id="tspan1-5"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="60.014114"
+         y="34.322666">Electronic</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="60.014114"
+         y="37.144897"
+         id="tspan2-6">parts</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2"
+       width="20"
+       height="10"
+       x="50"
+       y="30" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="34.950615"
+       y="21.058338"
+       id="text1-3-0"><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="34.950615"
+         y="21.058338"
+         id="tspan2-6-3">Firmware</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2-6"
+       width="20"
+       height="10"
+       x="25"
+       y="15" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="59.950615"
+       y="21.058338"
+       id="text1-3-0-1"><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="59.950615"
+         y="21.058338"
+         id="tspan2-6-3-8">Software</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2-6-7"
+       width="20"
+       height="10"
+       x="50"
+       y="15" />
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none"
+       id="rect3"
+       width="55"
+       height="35"
+       x="20"
+       y="10" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="20.802444"
+       y="43.971779"
+       id="text3"><tspan
+         sodipodi:role="line"
+         id="tspan3"
+         style="stroke-width:0.264583"
+         x="20.802444"
+         y="43.971779">Device</tspan></text>
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5"
+       width="65"
+       height="45"
+       x="15"
+       y="5" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 119.875,29.875 V 21.884426"
+       id="path9"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 119.875,29.874999 3,5"
+       id="path10" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 119.875,29.874999 -3,5"
+       id="path11" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 116.875,24.875001 h 6"
+       id="path12" />
+    <ellipse
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-dashoffset:0"
+       id="path13"
+       cx="119.875"
+       cy="19.384426"
+       rx="2.531951"
+       ry="2.5" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="116.39834"
+       y="38.57132"
+       id="text13"><tspan
+         sodipodi:role="line"
+         id="tspan13"
+         style="stroke-width:0.264583"
+         x="116.39834"
+         y="38.57132">User</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="107.72183"
+       y="48.361324"
+       id="text14"><tspan
+         sodipodi:role="line"
+         id="tspan14"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="107.72183"
+         y="48.361324">'API' as defined by</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="107.72183"
+         y="51.183556"
+         id="tspan15">Semantic Versioning</tspan></text>
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1"
+       d="M 91.000001,47.999998 80.874998,39.875"
+       id="path15"
+       sodipodi:nodetypes="cc" />
+  </g>
+</svg>
diff --git a/doc/diagrams/device-semver.svg b/doc/diagrams/device-semver.svg
deleted file mode 100644
index 8a68362..0000000
--- a/doc/diagrams/device-semver.svg
+++ /dev/null
@@ -1,223 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!-- Created with Inkscape (http://www.inkscape.org/) -->
-
-<svg
-   width="150mm"
-   height="55mm"
-   viewBox="0 0 150 55"
-   version="1.1"
-   id="svg1"
-   inkscape:version="1.3.2 (091e20ef0f, 2023-11-25, custom)"
-   sodipodi:docname="device-semver.svg"
-   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
-   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:svg="http://www.w3.org/2000/svg">
-  <sodipodi:namedview
-     id="namedview1"
-     pagecolor="#ffffff"
-     bordercolor="#666666"
-     borderopacity="1.0"
-     inkscape:showpageshadow="2"
-     inkscape:pageopacity="0.0"
-     inkscape:pagecheckerboard="0"
-     inkscape:deskcolor="#d1d1d1"
-     inkscape:document-units="mm"
-     showgrid="true"
-     inkscape:zoom="1.9638901"
-     inkscape:cx="240.08472"
-     inkscape:cy="127.80756"
-     inkscape:window-width="1916"
-     inkscape:window-height="1028"
-     inkscape:window-x="0"
-     inkscape:window-y="0"
-     inkscape:window-maximized="0"
-     inkscape:current-layer="layer1">
-    <inkscape:grid
-       id="grid1"
-       units="mm"
-       originx="0"
-       originy="0"
-       spacingx="0.99999999"
-       spacingy="0.99999999"
-       empcolor="#0099e5"
-       empopacity="0.30196078"
-       color="#0099e5"
-       opacity="0.14901961"
-       empspacing="5"
-       dotted="false"
-       gridanglex="30"
-       gridanglez="30"
-       visible="true" />
-  </sodipodi:namedview>
-  <defs
-     id="defs1" />
-  <g
-     inkscape:label="Ebene 1"
-     inkscape:groupmode="layer"
-     id="layer1">
-    <text
-       xml:space="preserve"
-       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
-       x="35.146614"
-       y="34.455166"
-       id="text1"><tspan
-         sodipodi:role="line"
-         id="tspan1"
-         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
-         x="35.146614"
-         y="34.455166">Mechanical</tspan><tspan
-         sodipodi:role="line"
-         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
-         x="35.146614"
-         y="37.277397"
-         id="tspan2">parts</tspan></text>
-    <rect
-       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
-       id="rect1"
-       width="20"
-       height="10"
-       x="25.1325"
-       y="30.1325" />
-    <text
-       xml:space="preserve"
-       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
-       x="60.014114"
-       y="34.322666"
-       id="text1-3"><tspan
-         sodipodi:role="line"
-         id="tspan1-5"
-         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
-         x="60.014114"
-         y="34.322666">Electronic</tspan><tspan
-         sodipodi:role="line"
-         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
-         x="60.014114"
-         y="37.144897"
-         id="tspan2-6">parts</tspan></text>
-    <rect
-       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
-       id="rect1-2"
-       width="20"
-       height="10"
-       x="50"
-       y="30" />
-    <text
-       xml:space="preserve"
-       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
-       x="34.950615"
-       y="21.058338"
-       id="text1-3-0"><tspan
-         sodipodi:role="line"
-         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
-         x="34.950615"
-         y="21.058338"
-         id="tspan2-6-3">Firmware</tspan></text>
-    <rect
-       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
-       id="rect1-2-6"
-       width="20"
-       height="10"
-       x="25"
-       y="15" />
-    <text
-       xml:space="preserve"
-       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
-       x="59.950615"
-       y="21.058338"
-       id="text1-3-0-1"><tspan
-         sodipodi:role="line"
-         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
-         x="59.950615"
-         y="21.058338"
-         id="tspan2-6-3-8">Software</tspan></text>
-    <rect
-       style="fill:none;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
-       id="rect1-2-6-7"
-       width="20"
-       height="10"
-       x="50"
-       y="15" />
-    <rect
-       style="fill:none;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none"
-       id="rect3"
-       width="55"
-       height="35"
-       x="20"
-       y="10" />
-    <text
-       xml:space="preserve"
-       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
-       x="20.802444"
-       y="43.971779"
-       id="text3"><tspan
-         sodipodi:role="line"
-         id="tspan3"
-         style="stroke-width:0.264583"
-         x="20.802444"
-         y="43.971779">Device</tspan></text>
-    <rect
-       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
-       id="rect5"
-       width="65"
-       height="45"
-       x="15"
-       y="5" />
-    <path
-       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="M 119.875,29.875 V 21.884426"
-       id="path9"
-       sodipodi:nodetypes="cc" />
-    <path
-       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 119.875,29.874999 3,5"
-       id="path10" />
-    <path
-       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 119.875,29.874999 -3,5"
-       id="path11" />
-    <path
-       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 116.875,24.875001 h 6"
-       id="path12" />
-    <ellipse
-       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-dashoffset:0"
-       id="path13"
-       cx="119.875"
-       cy="19.384426"
-       rx="2.531951"
-       ry="2.5" />
-    <text
-       xml:space="preserve"
-       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
-       x="116.39834"
-       y="38.57132"
-       id="text13"><tspan
-         sodipodi:role="line"
-         id="tspan13"
-         style="stroke-width:0.264583"
-         x="116.39834"
-         y="38.57132">User</tspan></text>
-    <text
-       xml:space="preserve"
-       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
-       x="107.72183"
-       y="48.361324"
-       id="text14"><tspan
-         sodipodi:role="line"
-         id="tspan14"
-         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
-         x="107.72183"
-         y="48.361324">'API' as defined by</tspan><tspan
-         sodipodi:role="line"
-         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
-         x="107.72183"
-         y="51.183556"
-         id="tspan15">Semantic Versioning</tspan></text>
-    <path
-       style="fill:none;stroke:#000000;stroke-width:0.264583;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1"
-       d="M 91.000001,47.999998 80.874998,39.875"
-       id="path15"
-       sodipodi:nodetypes="cc" />
-  </g>
-</svg>
diff --git a/doc/doc.mk b/doc/doc.mk
index 351cd48..d1e4a1b 100644
--- a/doc/doc.mk
+++ b/doc/doc.mk
@@ -3,7 +3,7 @@ DOCS := documentation
 DOCUMENTS := $(DOCS:%=$(DOC_BUILD_DIR)/%.pdf)
 
 DIAGRAMS_BUILD_DIR := $(DOC_BUILD_DIR)/diagrams
-DIAGRAMS := device-semver
+DIAGRAMS := device-semver-user device-semver-developer
 IMAGES := $(DIAGRAMS:%=$(DIAGRAMS_BUILD_DIR)/%.pdf)
 
 .PHONY: doc
diff --git a/doc/documentation.tex b/doc/documentation.tex
index 91ff8e5..5713b3c 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -30,13 +30,20 @@ Versioning\footnote{\href{https://semver.org}{https://semver.org}}. The
 resulting version numbers have the format \texttt{<major>.<minor>.<patch>} like
 e.g. \texttt{2.0.3}. While Semantic Versioning is usually targeted at software
 only it is here used for the whole device. This includes mechanical, electronic
-and software aspects as shown in figure \ref{diagram:device-semver}.
+and software aspects as shown in figure \ref{diagram:device-semver-user}.
 
 \begin{figure}[h]
 	\centering
-	\includegraphics[width=\textwidth]{device-semver.pdf}
-	\caption{API for a device versioned with Semantic Versioning}
-	\label{diagram:device-semver}
+	\includegraphics[width=\textwidth]{device-semver-user.pdf}
+	\caption{API for a device versioned with Semantic Versioning from a user perspective}
+	\label{diagram:device-semver-user}
+\end{figure}
+
+\begin{figure}[h]
+	\centering
+	\includegraphics[width=\textwidth]{device-semver-developer.pdf}
+	\caption{API for a device versioned with Semantic Versioning from a developer perspective}
+	\label{diagram:device-semver-developer}
 \end{figure}
 
 This versioning makes sure that users do not have to care about the device
-- 
cgit v1.2.3-70-g09d2