Neue Dokumentation mit komplett neuer Struktur erstellt und mit Bilde…

…rn versehen
Streckenkunde · Apr 5, 2024 · 30b7ac9 · 30b7ac9
1 parent 2e9511a
commit 30b7ac9
Show file tree

Hide file tree

Showing 40 changed files with 255 additions and 32 deletions.
diff --git a/docs/1_general/1_about.md b/docs/1_general/1_about.md
@@ -0,0 +1,17 @@
+# Über das Projekt
+
+Herzlich Willkommen zur Anwenderdokumentation für das Projekt "Streckenkunde Digital". Diese Dokumentation soll Ihnen
+als Anwender helfen, sich in der Software zurechtzufinden und die Funktionen zu verstehen. Die Software wurde speziell
+für Triebfahrzeugführer entwickelt, um die Dokumentation der Streckenkunde zu vereinfachen und zu digitalisieren. Bei
+Fragen oder Problemen können Sie sich gerne an den Support wenden. Die Kontaktdaten finden Sie am Ende dieser Seite.
+
+## Kontakt zum Support
+
+Der Support und die Weiterentwicklung des Projekts erfolgt durch folgenden Dienstleister:
+
+> Dennis Heinrich  
+> Veerßer Straße 86  
+> 29525 Uelzen
+>
+> Support-Mail: [support@dennis-heinri.ch](mailto:support@dennis-heinri.ch)  
+> Internetseite: [dennis-heinri.ch](https://dennis-heinri.ch)
diff --git a/docs/1_general/2_changes.md b/docs/1_general/2_changes.md
@@ -0,0 +1,25 @@
+# Dokumentation erweitern
+
+## Vorschlag zur Dokumentation einreichen
+
+Um einen Vorschlag zur Dokumentation einzureichen, erstellen Sie bitte ein Issue auf GitHub im Projekt zur
+Anwenderdokumentation. Dort können Sie die gewünschte Änderung oder eine Ergänzung mitteilen.
+
+> Hier können Sie [einen Vorschlag einreichen](https://github.com/Streckenkunde/Anwenderdokumentation/issues/new/choose)
+
+## Beitragen an der Dokumentation
+
+Wenn Sie an der Dokumentation mitarbeiten möchten, können Sie ihre Änderungen selbst in das Repository einpflegen.
+Dazu können Sie das Repository klonen und die Änderungen lokal vornehmen. Anschließend können Sie die Änderungen
+über einen Pull-Request einreichen und werden diese nach einer Prüfung in die Dokumentation überführen.
+
+> Mehr Informationen zum Beitragen finden Sie [in dem Repository](https://github.com/Streckenkunde/Anwenderdokumentation).
+
+### Voraussetzungen an den Beitragenden
+
+Zum Beitragen an der Dokumentation sind folgende Voraussetzungen notwendig:
+
+- *[Docker](https://docs.docker.com/get-docker)* um die Dokumentation zu kompilieren und zu starten
+- Das Tool *[Just](https://just.systems)*, es ist ein Management-Tool für das Ausführen von Befehlen
+- Erfahrung im Umgang mit Markdown-Dateien und der Versionsverwaltung *[Git](https://git-scm.com)*
+
diff --git a/docs/1_general/3_development.md b/docs/1_general/3_development.md
@@ -0,0 +1,13 @@
+# Entwicklung und Schnittstellen
+
+Die Software bietet eine spezielle Webseite (API), die es ermöglicht, Nutzerdaten zu bearbeiten. Diese Webseite ist über die Adresse `/api` erreichbar.
+
+- **OpenAPI-Spezifikation:** Es gibt eine Anleitung, wie man die API benutzt, die unter `/api/openapi.json` abrufbar ist.
+- **Interaktive Dokumentation:** Eine benutzerfreundlichere Version der Dokumentation findest du unter `/api/docs`.
+
+## Authentifizierung
+
+Um sicherzugehen, dass nur berechtigte Personen Zugang haben, nutzt die Software JWT-Token:
+
+- Nach dem Einloggen erhältst du einen JWT-Token von der Adresse `/api/login_check`.
+- Diesen Token musst du bei jeder Anfrage im `Authorization`-Bereich deiner Internetanfrage als Bearer-Token mitschicken.
diff --git a/docs/2_modules/1_welcome/assets/forgot_password.png b/docs/2_modules/1_welcome/assets/forgot_password.png
diff --git a/docs/2_modules/1_welcome/assets/login.png b/docs/2_modules/1_welcome/assets/login.png
diff --git a/docs/2_modules/1_welcome/assets/overview.png b/docs/2_modules/1_welcome/assets/overview.png
diff --git a/docs/2_modules/1_welcome/assets/registration.png b/docs/2_modules/1_welcome/assets/registration.png
diff --git a/docs/2_modules/1_welcome/index.md b/docs/2_modules/1_welcome/index.md
@@ -0,0 +1,23 @@
+# Startseite
+
+Jeder Nutzer ohne eine gültige Anmeldung wird auf der Willkommensseite begrüßt. Hier kann sich der Nutzer entweder anmelden oder ein neues Benutzerkonto registrieren. Außerdem gibt es die Möglichkeit, ein neues Passwort anzufordern, falls der Nutzer sein Passwort vergessen hat.
+
+![*](./assets/overview.png)
+
+## Anmeldung mit vorhandenem Benutzerkonto
+
+Jeder Nutzer kann sich auf der Plattform registrieren und anmelden. Dazu wird ein Benutzername und ein Passwort benötigt. Die Anmeldung erfolgt über die Webseite und ist für jeden Nutzer zugänglich. Der Benutzername ist die E-Mail-Adresse, die bei der Registrierung angegeben wurde. Das Passwort wird bei der Registrierung festgelegt und kann jederzeit durch die Passwort-Vergessen Funktion geändert werden.
+
+![*](./assets/login.png)
+
+## Registrierung eines neuen Benutzerkontos
+
+Um ein neues Benutzerkonto zu registrieren, muss der Nutzer auf der Webseite die Registrierungsfunktion aufrufen. Dazu wird ein Benutzername (E-Mail), der vollständige Name des Anwenders und ein Passwort benötigt.
+
+![*](./assets/registration.png)
+
+## Passwort vergessen
+
+Wenn ein Nutzer sein Passwort vergessen hat, kann er über die Webseite ein neues Passwort anfordern. Dazu wird die E-Mail-Adresse benötigt, die bei der Registrierung angegeben wurde. Der Nutzer erhält dann eine E-Mail mit einem neuen Passwort zur vorrübergehenden Anmeldung.
+
+![*](./assets/forgot_password.png)
diff --git a/docs/2_modules/2_dashboard/assets/filter_all.png b/docs/2_modules/2_dashboard/assets/filter_all.png
diff --git a/docs/2_modules/2_dashboard/assets/filter_exclusive.png b/docs/2_modules/2_dashboard/assets/filter_exclusive.png
diff --git a/docs/2_modules/2_dashboard/assets/overview.png b/docs/2_modules/2_dashboard/assets/overview.png
diff --git a/docs/2_modules/2_dashboard/index.md b/docs/2_modules/2_dashboard/index.md
@@ -0,0 +1,22 @@
+# Dashboard
+
+Auf dem Dashboard sieht der Nutzer eine Übersicht zum Verfall seiner dokumentierten Streckenkunden, allgemeine Informationen zu seinem Benutzerkonto und eine kleine Statistik über die Anzahl der von ihm eingepflegten Strecken und Touren.
+
+![*](./assets/overview.png)
+
+## Verfallsübersicht
+
+In diesem Modul hat der Nutzer die Möglichkeit, sich einen Überblick über den Verfall seiner Streckenkunden zu verschaffen. Hier werden alle Streckenkunden aufgelistet, die in seinem festgelegten Zeitraum (Auswahl der Tage) ablaufen werden. Der Nutzer kann zudem die Strecken rausfiltern, die er noch nie dokumentiert hat. Dafür kann er die Checkbox "Nur aufgezeichnete Strecken" verwenden.
+
+### Nur aufgezeichnete Strecken
+
+Es werden nur die Strecken angezeigt, die bereits in der Vergangenheit dokumentiert wurden und in dem angebenen Zeitraum der Tage ablaufen werden und somit ein Verfallsdatum haben.
+Abgelaufene Strecken werden immer angezeigt, unabhängig der Filter.
+
+![*](./assets/filter_exclusive.png)
+
+### Alle Strecken anzeigen
+
+Alle Strecken werden angezeigt, unabhängig davon, ob sie bereits dokumentiert wurden oder nicht. In diesem Fall wird unter der Strecke "Keine Aufzeichnung" dargestellt und alle Strecken die unter dieses Kriterium fallen, werden ganz oben in der Liste dargestellt. Abgelaufene Strecken werden immer angezeigt, unabhängig der Filter.
+
+![*](./assets/filter_all.png)
diff --git a/docs/2_modules/3_documentation/1_routes/assets/create.png b/docs/2_modules/3_documentation/1_routes/assets/create.png
diff --git a/docs/2_modules/3_documentation/1_routes/assets/edit.png b/docs/2_modules/3_documentation/1_routes/assets/edit.png
diff --git a/docs/2_modules/3_documentation/1_routes/assets/view.png b/docs/2_modules/3_documentation/1_routes/assets/view.png
diff --git a/docs/2_modules/3_documentation/1_routes/assets/view_not_documented.png b/docs/2_modules/3_documentation/1_routes/assets/view_not_documented.png
diff --git a/docs/2_modules/3_documentation/1_routes/index.md b/docs/2_modules/3_documentation/1_routes/index.md
@@ -0,0 +1,33 @@
+# Strecken
+
+Eine Strecke ist ein Abschnitt im Schienennetz, der von einem Start- zu einem Endpunkt führt. Die Strecke besteht immer aus einem Namen, zwei Punkten (Start und Endpunkt) und optional einem Namen, der Unternehmensintern verwendet wird. Die Strecke kann auch in einer Tour inbegriffen sein, um die Dokumentation mehrerer Strecken zu vereinfachen.
+
+## Erstellen
+
+Um eine neue Strecke zu erstellen, klicke auf den Button "Strecke erstellen" auf der Seite [Dokumentation](../index.md). Es öffnet sich ein Dialog, in dem du die notwendigen Informationen eingeben kannst.
+
+- **Name:** Der Name der Strecke.
+- **Unternehmens-Kürzel:** (optional) Bezeichner für die Strecke.
+- **Start der Strecke:** Der Startpunkt der Strecke.
+- **Ende der Strecke:** Der Endpunkt der Strecke.
+- **Zuletzt gefahren am:** (optional) Das Datum, an dem die Strecke zuletzt befahren wurde.
+    - Standardmäßig wird kein Datum angegeben.
+    - Mit Eintrag wird die Strecke zur Erstellung mit der Streckenkunde vermerkt.
+
+![Strecke erstellen](./assets/create.png)
+
+## Ansehen
+
+Um eine Strecke anzusehen, klicke auf den Namen der Strecke an einem beliebigen Punkt innerhalb der Anwendung. Es öffnet sich ein Dialog, in dem du die Informationen zur Strecke einsehen kannst. Die Strecke kann z.B. über die Suche der [Dokumentation](../index.md) gefunden werden. Es werden alle Daten, sowie die Gültigkeit der Streckenkunde angezeigt.
+
+![Strecke ansehen](./assets/view.png)
+
+Hat die Strecke keine dokumentierte Streckenkunde, wird dies mit "Nicht erfasst" gekennzeichnet
+
+![Strecke ohne Dokumentation](./assets/view_not_documented.png)
+
+## Bearbeiten
+
+Um eine Strecke zu bearbeiten, klicke auf den Namen der Strecke an einem beliebigen Punkt innerhalb der Anwendung um die Strecke anzusehen. Anschließend klicke auf den Button "Strecke bearbeiten". Es öffnet sich ein Dialog, in dem du die notwendigen Informationen ändern oder die Strecke komplett löschen kannst. Die Strecke kann z.B. über die Suche der [Dokumentation](../index.md) gefunden werden.
+
+![Strecke bearbeiten](./assets/edit.png)
diff --git a/docs/2_modules/3_documentation/2_tours/assets/create.png b/docs/2_modules/3_documentation/2_tours/assets/create.png
diff --git a/docs/2_modules/3_documentation/2_tours/assets/edit.png b/docs/2_modules/3_documentation/2_tours/assets/edit.png
diff --git a/docs/2_modules/3_documentation/2_tours/assets/view.png b/docs/2_modules/3_documentation/2_tours/assets/view.png
diff --git a/docs/2_modules/3_documentation/2_tours/index.md b/docs/2_modules/3_documentation/2_tours/index.md
@@ -0,0 +1,23 @@
+# Touren
+
+Eine Tour ist z.B. eine Fahrt von Hamburg nach Berlin, welche viele [Strecken](../2_tours/index.md) beinhaltet. Somit können auf oft befahrenen Abschnitten oder vorgefertigten Touren die Strecken mit einem einzelnen Klick in der [Dokumentation](../index.md) übernommen werden, statt alle Strecken vereinzelt zu markieren.
+
+## Erstellen
+
+Die Erstellung einer Tour erfolgt über den Button "Tour erstellen" auf der Seite [Dokumentation](../index.md). Die Tour benötigt einen Namen und mindestens zwei Strecken, um erstellt werden zu können. Die Strecken können über die Suchfunktion ausgewählt werden, und wie bei der Dokumentation markiert werden. Alle markierten Strecken sind dann Bestandteil der Tour.
+
+![*](./assets/create.png)
+
+## Ansehen
+
+Um eine Tour anzusehen, klicke auf den Namen einer Tour an einem beliebigen Punkt innerhalb der Anwendung. Es öffnet sich ein Dialog, in dem die Informationen, sowie die beinhalteten Strecken einer Tour eingesehen werden können. Eine Tour kann z.B. über die Suche der [Dokumentation](../index.md) gefunden werden. Über einen Klick auf eine der Strecken in der Tour gelangst du zur Einzelansicht dieser.
+
+![*](./assets/view.png)
+
+## Bearbeiten
+
+Um eine Tour zu bearbeiten, klicke auf den Namen einer Tour an einem beliebigen Punkt innerhalb der Anwendung um die Tour anzusehen. Anschließend klicke auf den Button "Tour bearbeiten". Es öffnet sich ein Dialog, in dem du die notwendigen Informationen, sowie die beinhalteten Strecken ändern oder die Tour gänzlich löschen kannst. 
+
+Wenn die Auswahl der beinhalteten Strecken geändert werden, sind diese erst nach dem Speichern aktiv. Die Anwendung merkt sich dennoch die vorherige Auswahl, z.B. um Strecken zwischenzeitlich zu öffnen oder zu bearbeiten. Kehrt man zur Bearbeitung zurück, sind die Strecken wieder markiert. Die Auswahl der geänderten Strecken ohne Speichern wird verworfen, wenn auf "Zurück zur Ansicht" geklickt wird.
+
+![*](./assets/edit.png)
diff --git a/docs/2_modules/3_documentation/assets/documentation.png b/docs/2_modules/3_documentation/assets/documentation.png
diff --git a/docs/2_modules/3_documentation/assets/overview.png b/docs/2_modules/3_documentation/assets/overview.png
diff --git a/docs/2_modules/3_documentation/index.md b/docs/2_modules/3_documentation/index.md
@@ -0,0 +1,25 @@
+# Dokumentation
+
+Auf dieser Seite hat der Nutzer die Möglichkeit:
+
+1. Seine Streckenkunden zu dokumentieren
+2. Strecken anzuzeigen oder zu erstellen
+3. Touren anzuzeigen oder zu erstellen
+
+![*](./assets/overview.png)
+
+## Strecken
+
+Eine Strecke ist ein Abschnitt im Schienennetz, der von einem Start- zu einem Endpunkt führt. Die Strecke besteht immer aus einem Namen, zwei Punkten (Start und Endpunkt) und optional einem Namen, der Unternehmensintern verwendet wird. Die Strecke kann auch in einer Tour inbegriffen sein, um die Dokumentation mehrerer Strecken zu vereinfachen.
+
+## Touren
+
+Eine Tour enthält mehrere Strecken. Eine Tour kann beispielsweise eine Fahrt von Hamburg nach Berlin sein. In diesem Fall würde die Tour alle Strecken enthalten, die auf dieser Fahrt zurückgelegt werden. Somit können auf oft befahrenen Abschnitten oder vorgefertigten Touren die Strecken mit einem einzelnen Klick in die Dokumentation übernommen werden, statt diese alle vereinzelt zu markieren.
+
+## Dokumentieren
+
+Die Dokumentation einer Streckenkunde erfolgt über die Markierung der gefahrenen Touren oder einzelner Strecken. Die Markierung erfolgt mit dem Lesezeichen-Symbol. Über erneuten Klick kann die Markierung wieder entfernt werden.
+
+Wenn mindestens ein Element markiert wurde, erscheint das Modul zur Dokumentation der Streckenkunde. Hier kann der Nutzer ein Datum festlegen, an dem die Streckenkunde erworben wurde. Standardmäßig ist immer das aktuelle Datum vorausgewählt. Der Ablauf der Streckenkunde wird automatisch berechnet und für ein Jahr festgelegt (364 Tage nach Erwerbsdatum).
+
+![*](./assets/documentation.png)
diff --git a/docs/2_modules/4_account/assets/overview.png b/docs/2_modules/4_account/assets/overview.png
diff --git a/docs/2_modules/4_account/index.md b/docs/2_modules/4_account/index.md
@@ -0,0 +1,6 @@
+# Übersicht
+
+Das Modul "Account" bietet dem Nutzer die Möglichkeit, seine persönlichen Daten anzuzeigen. Eine Bearbeitung der Daten ist zum 
+derzeitigen Stand der Anwendung nicht möglich.
+
+![Übersicht](./assets/overview.png)
diff --git a/docs/3_extras/1_app/assets/desktop_chrome/desktop_icon.png b/docs/3_extras/1_app/assets/desktop_chrome/desktop_icon.png
diff --git a/docs/3_extras/1_app/assets/desktop_chrome/finish.png b/docs/3_extras/1_app/assets/desktop_chrome/finish.png
diff --git a/docs/3_extras/1_app/assets/desktop_chrome/install_1.png b/docs/3_extras/1_app/assets/desktop_chrome/install_1.png
diff --git a/docs/3_extras/1_app/assets/desktop_chrome/install_2.png b/docs/3_extras/1_app/assets/desktop_chrome/install_2.png
diff --git a/docs/3_extras/1_app/assets/smartphone_android/app_details.png b/docs/3_extras/1_app/assets/smartphone_android/app_details.png
diff --git a/docs/3_extras/1_app/assets/smartphone_android/finish.png b/docs/3_extras/1_app/assets/smartphone_android/finish.png
diff --git a/docs/3_extras/1_app/assets/smartphone_android/install.png b/docs/3_extras/1_app/assets/smartphone_android/install.png
diff --git a/docs/3_extras/1_app/assets/smartphone_apple/Thumbs.db b/docs/3_extras/1_app/assets/smartphone_apple/Thumbs.db
diff --git a/docs/3_extras/1_app/assets/smartphone_apple/install_1.jpg b/docs/3_extras/1_app/assets/smartphone_apple/install_1.jpg
diff --git a/docs/3_extras/1_app/assets/smartphone_apple/install_2.jpg b/docs/3_extras/1_app/assets/smartphone_apple/install_2.jpg
diff --git a/docs/3_extras/1_app/index.md b/docs/3_extras/1_app/index.md
@@ -0,0 +1,49 @@
+# Installation als App
+
+## Desktop
+
+### Google Chrome
+
+Die Seite kann als App (PWA) auf dem Desktop installiert werden. Dazu wird die Seite im Browser geöffnet und die Option "Installieren" neben der URL-Eingabe ausgewählt.
+
+![*](./assets/desktop_chrome/install_1.png)
+
+Es öffnet sich ein Dialog, in dem die Installation bestätigt werden muss.
+
+![*](./assets/desktop_chrome/install_2.png)
+
+Anschließend wird die App als Icon und auf dem Desktop abgelegt.
+
+![*](./assets/desktop_chrome/desktop_icon.png)
+
+Nach dem Start der App wird die Anwendung in einem eigenen Fenster geöffnet.
+
+![*](./assets/desktop_chrome/finish.png)
+
+## Smartphone
+
+### Android mit Google Chrome
+
+Die Seite kann als App (PWA) auf dem Smartphone installiert werden. Dazu wird die Seite im Browser geöffnet und die Option "App Installieren" in den Einstellungen (Drei-Punkte-Icon) des Chrome-Browsers ausgewählt. Dann wird die Installation bestätigt.
+
+![*](./assets/smartphone_android/install.png)
+
+Anschließend wird die App als Icon auf dem Startbildschirm abgelegt und kann dort als App gestartet werden.
+
+![*](./assets/smartphone_android/finish.png)
+
+Die App ist auch über die App-Übersicht erreichbar, wo sie als eigenständige App angezeigt wird und auch deinstalliert werden kann.
+
+![*](./assets/smartphone_android/app_details.png)
+
+### Apple / iOS
+
+Auf iOS-Geräten kann die App nicht installiert werden, da Apple keine PWAs unterstützt. Die Seite kann jedoch als Startbildschirm-Lesezeichen über Safari hinzugefügt werden, um sie schneller zu öffnen. Dafür wird die Seite im Safari-Browser geöffnet und die Option "Zum Home-Bildschirm" in den Einstellungen (Teilen-Icon) ausgewählt.
+
+![*](./assets/smartphone_apple/install_1.jpg)
+
+Anschließend wird die Installation mit der Vergabe eines Namens bestätigt.
+
+![*](./assets/smartphone_apple/install_2.jpg)
+
+Die Anwendung wird als Icon auf dem Startbildschirm abgelegt und kann dort als Lesezeichen gestartet werden.
diff --git a/docs/3_extras/index.md b/docs/3_extras/index.md
@@ -0,0 +1 @@
+# Übersicht
diff --git a/docs/index.md b/docs/index.md
@@ -1,17 +1 @@
-# Einleitung
-
-Herzlich Willkommen zur Anwenderdokumentation für das Projekt "Streckenkunde Digital". Diese Dokumentation soll Ihnen
-als Anwender helfen, sich in der Software zurechtzufinden und die Funktionen zu verstehen. Die Software wurde speziell
-für Triebfahrzeugführer entwickelt, um die Dokumentation der Streckenkunde zu vereinfachen und zu digitalisieren. Bei
-Fragen oder Problemen können Sie sich gerne an den Support wenden. Die Kontaktdaten finden Sie am Ende dieser Seite.
-
-## Kontakt zum Support
-
-Der Support und die Weiterentwicklung des Projekts erfolgt durch folgenden Dienstleister:
-
-> Dennis Heinrich  
-> Veerßer Straße 86  
-> 29525 Uelzen
->
-> Support-Mail: [support@dennis-heinri.ch](mailto:support@dennis-heinri.ch)  
-> Internetseite: [dennis-heinri.ch](https://dennis-heinri.ch)
+In dieser Anwenderdokumentation finden Sie Informationen zur Bedienung der Software. Die Dokumentation ist in verschiedene Abschnitte unterteilt, die sich mit unterschiedlichen Modulen des Programms beschäftigen. Die Abschnitte sind in der linken Navigationsleiste aufgelistet.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,6 +8,7 @@ theme:
     primary: black
     accent: teal
   features:
+    - toc.follow
     - navigation.footer
 
 extra:
@@ -17,18 +18,19 @@ extra:
       link: https://github.com/cloudmaker97
 
 nav:
-  - Einleitung: index.md
-  - Konto und Einstellungen:
-      - Startseite: user/index.md
-      - Dashboard: user/dashboard.md
-      - Kontoverwaltung: user/account.md
-      - Benachrichtigungen: user/notifications.md
-  - Dokumentation:
-      - Dokumentation von Streckenkunden: manage/activity.md
-      - Strecken verwalten: manage/route.md
-      - Touren verwalten: manage/tour.md
-      - Export der Daten: manage/export.md
-  - Sonstiges:
-      - Dokumentation: development/documentation.md
-      - Schnittstelle: development/api.md
-      - Updates: development/updates.md
+  - Startseite: index.md
+  - Allgemeines:
+    - 1_general/1_about.md
+    - 1_general/2_changes.md
+    - 1_general/3_development.md
+  - Funktionen und Module:
+    - 2_modules/1_welcome/index.md
+    - 2_modules/2_dashboard/index.md
+    - Dokumentation:
+      - 2_modules/3_documentation/index.md
+      - 2_modules/3_documentation/1_routes/index.md
+      - 2_modules/3_documentation/2_tours/index.md
+    - Mein Konto:
+      - 2_modules/4_account/index.md
+  - Weitere Informationen:
+    - 3_extras/1_app/index.md