Die Dokumentation des aktuellen Standes Ihrer Software (README.md)

➔ Eine Beispiel-README.md wird im Anschluss bereitgestellt und kann direkt bearbeitet werden.

Was ist eine Projektdokumentation?

Eine Projektdokumentation beschreibt alle wichtigen Informationen zu Ihrer Software. Sie enthält unter anderem:

• ✅ Den Projektnamen und eine kurze Zusammenfassung
• ✅ Verwendete Technologien und deren Versionen
• ✅ Installations- und Nutzungshinweise
• ✅ Bekannte Probleme und offene Punkte
• ✅ Reflexionen zu Schwierigkeiten und Lernerfolgen

Warum ist eine Dokumentation wichtig?

Die Dokumentation ermöglicht es anderen Personen, Ihr Projekt zu verstehen und weiterzuentwickeln. Sie zeigt, dass Sie strukturiert und professionell arbeiten – eine grundlegende Kompetenz in allen Softwareprojekten.

Was ist Markdown (.md)?

Markdown ist eine einfache Auszeichnungssprache, mit der Sie Textdateien strukturieren und formatieren können. README-Dateien auf Plattformen wie GitHub nutzen häufig das Markdown-Format, da es leicht lesbar und gleichzeitig gut strukturiert ist.

Beispiel für Markdown-Formatierung:

# Überschrift 1
## Überschrift 2
**Fett**  
*Kursiv*  
- Listeintrag
`Code inline`

```python
print("Hello World")

Wie können Sie Ihre README.md bearbeiten?

1. Die Beispiel-README.md kopieren und lokal speichern

• macOS: Öffnen Sie TextEdit, stellen Sie auf „Plain Text“ um und fügen Sie den Inhalt ein. Speichern Sie die Datei als README.md.
• Windows: Öffnen Sie Editor oder Notepad++, fügen Sie den Inhalt ein und speichern Sie als README.md.
• Visual Studio Code (empfohlen): Öffnen Sie VSCode, erstellen Sie eine neue Datei, fügen Sie den Inhalt ein und speichern Sie diese als README.md.

2. Beispiel-README.md bearbeiten und anpassen

Im Folgenden finden Sie eine Beispiel-README.md. Diese Vorlage enthält alle wichtigen Abschnitte, die in einer Projektdokumentation enthalten sein sollten.

Aufgabe:

1. Kopieren Sie die gesamte Beispiel-README.md in Ihren lokalen Editor (z.B. VSCode, TextEdit oder Notepad++).
2. Lesen Sie alle Abschnitte aufmerksam durch und bearbeiten Sie die Datei abschnittsweise – nicht alles auf einmal.
3. Ersetzen Sie die Platzhalter durch Ihre eigenen Projektdaten, z.B. Projektname, tatsächliche Versionen Ihrer installierten Programme und persönliche Reflexionen. Löschen Sie alle Platzhalter danach.
4. Verbinden Sie sich mit Ihrem Server via SSH, um:
   • Ihre aktuelle Verzeichnisstruktur zu überprüfen (ls -a, tree)
   • Die verwendeten Technologien und deren Versionen zu ermitteln (z.B. python3 --version, pip show flask | grep Version, mysql --version)
5. Beantworten Sie alle Reflexionsfragen ehrlich und ausführlich. Diese helfen Ihnen, Ihre Lernfortschritte zu erkennen und dokumentieren.
6. Verwenden Sie bei Bedarf gerne KI-Tools (z.B. ChatGPT), um einzelne Abschnitte auszuformulieren oder Beispiele zu generieren. In der Beispiel-README.md finden Sie Beispielprompts.
7. Speichern Sie die bearbeitete Datei als README.md.
8. Laden Sie die fertige Datei anschließend auf Ihren Server hoch, wie in den nachfolgenden Schritten beschrieben. (unter der Beispiel-Readme!)

Hier können Sie die Beispiel-README.md herunterladen und in Ihrem Editor (VSCode, TextEdit, Notepad++) öffnen und bearbeiten.

Im nächsten Abschnitt finden Sie die vollständige Beispiel-README.md.

Beispiel README.md

	# 📘 Projektdokumentation (README.md)

Herzlich willkommen zu Ihrer Projektdokumentation!  
Diese README.md hilft Ihnen dabei, Ihr Projekt **klar, vollständig und verständlich zu dokumentieren**.

---

## 📝 1. Projekttitel

✏️ **Aufgabe:** Geben Sie Ihrem Projekt einen passenden Namen.  
💡 **Beispiel:** Escape Room Webapp – Gruppe ISA##

---

## 📝 2. Projektbeschreibung

✏️ **Aufgabe:** Beschreiben Sie in **einfachen Worten**:

- Was macht Ihr Projekt?
- Für wen ist es gedacht?
- Was ist das Ziel?

💡 **Beispiel-Prompt für ChatGPT:**  
„Beschreibe meine Webanwendung in 3 einfachen Sätzen. Sie ist ein Escape Room Spiel mit HTML, CSS, JS, Flask und MariaDB.“

---

### 📂 Ordnerstruktur des www-Verzeichnisses

✏️ **Aufgabe:** Geben Sie hier die Struktur Ihres `home`-Ordners an. Verwenden Sie dazu den folgenden Befehl auf Ihrem Server. 

**Befehl:**```bash
tree /home/isa## -L 3```

> 📝 **Hinweis:**  
> - `tree` zeigt Ihnen die Ordner und Dateien als Baumstruktur an.  
> - `-L 3` bedeutet, dass **maximal 3 Ebenen** angezeigt werden.  




## 🛠️ 3. Verwendete Technologien und Versionen

Hier tragen Sie ein, **welche Programme, Frameworks und Tools** Sie verwendet haben.  
👉 **Führen Sie dazu die Befehle direkt auf Ihrem Server aus** und kopieren Sie die Ergebnisse hier hinein.

---

### 🔢 Python Version

**Befehl:```python3 --version```

✏️ **Ergebnis hier eintragen:** Python ...

---

### 🔢 Flask Version

**Befehl:**```source venv/bin/activate
pip show flask | grep Version```

✏️ **Ergebnis hier eintragen:** Flask ...

---

### 🔢 MariaDB Version

**Befehl:**```
mysql --version```

✏️ **Ergebnis hier eintragen:** MariaDB ...

---

### 🔢 Git Version

**Befehl:**```
git --version```

✏️ **Ergebnis hier eintragen:** Git ...

---

### 🔢 Frontend Technologien

HTML, CSS, JavaScript (verwenden Standardbrowser wie Chrome oder Firefox)

---



## 📝 4. Tutorials & Inhalte

✏️ **Aufgabe:** Schreiben Sie hier stichpunktartig, welche Tutorials (U0 – U7) Sie bearbeitet haben und was Sie dort gelernt haben.

💡 **Beispiel:**

- **U0:** Terminal Grundlagen (Ordner, Dateien, Navigation)
- **U1:** SSH Schlüssel erstellen und Verbindung zum Server
- **U2:** Erste Landingpage mit HTML/CSS
- **U3:** Mehrere Seiten & responsives Design
- **U4:** Flask Hello World
- **U5:** Escape Room Projekt starten
- **U6:** Datenbank (MariaDB) einbinden
- **U7:** Git Grundlagen & Versionierung

---

## ⚙️ 5. Installationsanleitung

✏️ **Aufgabe:** Erklären Sie Schritt für Schritt, wie man Ihr Projekt startet.

💡 **Beispiel:**

1. Virtuelle Umgebung erstellen:

Wie erstellt man eine virtuelle Umgebung und wie startet man diese?
Sie wissen es nicht mehr? Schauen Sie im entsprechenden Tutorial nach :)

2. Flask installieren:

Wie installiert man Flask?

3. Anwendung starten:

Wie heißt die Hauptanwendung und wie startet man diese? (app.py)

4. Im Browser aufrufen:

Wie ruft man Ihre Anwendung auf? URL mit Port?



---

## 💡 6. Nutzung & Bedienung

✏️ **Aufgabe:** Beschreiben Sie einfach und klar:

- Welche Seiten/Funktionen hat Ihre Anwendung?
- Wie navigiert der Benutzer?

💡 **Prompt:** „Welche Funktionen hat meine Escape Room App und wie benutzt man sie?“

---

## 🐞 7. Bekannte Probleme & Bugs

✏️ **Aufgabe:** Listen Sie bekannte Fehler, Bugs oder unvollständige Funktionen auf.

💡 **Beispiel:**

- CSS nicht responsive auf Handy
- Datenbankabfrage für Rätsel funktioniert nicht stabil

---

## ✨ 8. Reflexion

Reflektieren Sie Ihre Lernerfahrungen ehrlich.

### ✅ Was lief gut?

✏️ **Aufgabe:** Wo hatten Sie Erfolgserlebnisse?

---

### ⚠️ Wo gab es Schwierigkeiten?

✏️ **Aufgabe:** Welche Themen waren herausfordernd?

---

### 🎯 Was möchten Sie im M2-Softwareprojekt vertiefen?

✏️ **Aufgabe:** Was interessiert Sie für das nächste Semester besonders?

---

## 📋 9. To-Do-Liste

✏️ **Aufgabe:** Markieren Sie, was bereits erledigt ist, und ergänzen Sie offene Punkte.

- [x] SSH-Verbindung hergestellt
- [x] HTML Landing Page erstellt
- [x] CSS gestaltet
- [x] Flask installiert & gestartet
- [x] Escape Room Rätsellogik programmiert
- [x] MariaDB eingebunden
- [ ] Responsives Design finalisiert
- [ ] Dokumentation abgeschlossen

---

## 🤖 10. Prompts zur Unterstützung

Verwenden Sie bei Bedarf KI-Tools wie ChatGPT und formulieren Sie eigene Prompts. Beispiele:

- „Erstelle eine Projektbeschreibung für eine Escape Room App mit Flask und MariaDB.“
- „Formuliere eine klare Installationsanleitung für mein Flask Projekt.“
- „Hilf mir, meine Reflexionsfragen strukturiert zu beantworten.“

---

✅ **Wichtig:**  
Bitte löschen Sie alle Platzhalter, Prompts und Beispieltexte vor Abgabe.

---

Ende der Beispiel-README.md.

3. Die Datei auf den Server hochladen

Verwenden Sie dazu das Terminal mit dem folgenden SCP-Befehl:

scp -P 2222 README.md st3fr1@edumake.de:/home/isa##/www/

Ersetzen Sie ## durch Ihre Benutzer- oder Gruppennummer.

4. Datei auf dem Server überprüfen

Verbinden Sie sich via SSH und prüfen Sie, ob die Datei korrekt hochgeladen wurde:

ssh -p 2222 st3fr1@edumake.de
cd www
cat README.md

Anmeldung bei GitHub und Hochladen Ihres Projekts

Offizielle GitHub-Dokumentation

Sie finden die ausführliche Anleitung direkt bei GitHub unter:
https://docs.github.com/de/get-started/start-your-journey/uploading-a-project-to-github

Warum GitHub?

GitHub ist eine Plattform, auf der Sie Ihre Projekte online speichern, versionieren und mit anderen teilen können. Dies ist ein wichtiger Standard in der Softwareentwicklung und wird auch im Modul M2 genutzt.

🔎 Was ist ein Repository?

Ein Repository (kurz „Repo“) ist ein Speicherort auf GitHub, in dem Ihr Projekt liegt. Es enthält alle Dateien, Ordner, Dokumentationen und die Versionshistorie Ihres Projekts. Sie können es sich wie einen Projektordner vorstellen, der online verfügbar ist.

Schritt 1: Anmeldung bei GitHub

Falls Sie noch kein Konto besitzen, registrieren Sie sich unter https://github.com.

Schritt 2: Projekt bei GitHub hochladen

🔹 Möglichkeit A: Hochladen über die GitHub-Weboberfläche (empfohlen für Anfänger)

1. Gehen Sie zu GitHub und melden Sie sich an.
2. Klicken Sie oben rechts auf „+“ ➔ „New repository“.
3. Geben Sie einen passenden Namen für Ihr Repository ein, z.B. isa16-projekt, und klicken Sie auf „Create repository“.
4. Laden Sie Ihren gesamten Benutzerordner herunter (außer .ssh). Führen Sie folgenden Befehl mit ihrem Benutzernamen auf ihrem Terminal/powershell lokal aus. Ersetzen Sie ## durch Ihren Benutzernamen
   Bash Copy Text

   scp -P 2222 -r isa##@edumake.de:/home/isa## ~/Downloads/isa16

5. Klicken Sie in Ihrem Repository auf „Add file“ ➔ „Upload files“.
6. Ziehen Sie die heruntergeladenen Dateien (ohne .ssh) hinein oder laden Sie sie als ZIP-Datei hoch.
7. Scrollen Sie nach unten und klicken Sie auf „Commit changes“.

🔹 Möglichkeit B: Hochladen direkt vom Server (fortgeschritten)

1. Auf dem Server in Ihren Projektordner wechseln:
   Bash Copy Text

   cd /home/isa16
   git init
   git add .
   git commit -m "Initial commit"

2. .ssh vom Commit ausschließen:
   Bash Copy Text

   echo ".ssh/" >> .gitignore
   git add .gitignore
   git commit -m "Add .gitignore to exclude SSH keys"

3. Repository mit GitHub verbinden und Push ausführen:
   Bash Copy Text

   git remote add origin https://github.com/IHRBENUTZERNAME/IHRREPOSITORY.git
   git branch -M main
   git push -u origin main

💡 Tipp: Nutzen Sie bei der ersten Verbindung Ihr GitHub-Passwort oder ein Personal Access Token (PAT).

Wichtige Hinweise

• 🔒 Sensible Daten anonymisieren! Löschen oder ersetzen Sie Passwörter, Benutzernamen und Zugangsdaten in Konfigurationsdateien durch Platzhalter, bevor Sie Ihr Projekt öffentlich hochladen.
• ⚠️ Niemals Ihre .ssh-Datei oder private Schlüssel hochladen.

Einschub für Windows Nutzer

💻 Optionen für Windows-Nutzer

✅ Möglichkeit 1: PowerShell mit OpenSSH (Windows 10 ab Version 1809)

1. Öffnen Sie PowerShell.
2. Prüfen Sie, ob scp verfügbar ist, indem Sie eingeben:
   PowerShell Copy Text

   scp

3. Falls scp verfügbar ist, können Sie folgenden Befehl ausführen (passen Sie den Zielpfad an Ihren Benutzernamen an):
PowerShell Copy Text

scp -P 2222 -r isa16@edumake.de:/home/isa16 C:\\Users\\DEINNAME\\Downloads\\isa16

4. Hinweis: Ersetzen Sie DEINNAME durch Ihren Windows-Benutzernamen, z.B.:
PowerShell Copy Text

C:\Users\stefan\Downloads\isa16

✅ Möglichkeit 2: WinSCP (empfohlen für Anfänger)

1. Laden Sie WinSCP herunter und installieren Sie es.
2. Öffnen Sie WinSCP und verbinden Sie sich mit:
   • Host: edumake.de
   • Port: 2222
   • Benutzername: isa16
3. Nach der Anmeldung:
   • Wechseln Sie in das Verzeichnis /home/isa16.
   • Markieren Sie den gesamten Ordnerinhalt (außer .ssh).
   • Ziehen Sie die Dateien per Drag & Drop in Ihren lokalen Downloads-Ordner.

✅ Möglichkeit 3: Git Bash (falls installiert)

1. Öffnen Sie Git Bash (Teil von Git for Windows).
2. Führen Sie denselben Befehl wie unter Mac/Linux aus:
   Git Bash Copy Text

   scp -P 2222 -r isa16@edumake.de:/home/isa16 ~/Downloads/isa16

Ausblick auf das kommende Softwareprojekt (M2)

🔎 Motivation

Herr Franke und Herr Müller werden Ihnen im kommenden Semester wieder verschiedene Themenvorschläge für Softwareprojekte vorstellen. Dennoch hat sich gezeigt, dass Projekte, bei denen Sie selbst eine intrinsische Motivation mitbringen, oft erfolgreicher und nachhaltiger umgesetzt werden.

💭 Leitfragen für Ihre Themenfindung

Stellen Sie sich vorab folgende Fragen:

• Was interessiert mich persönlich besonders?
• Wo gibt es Themengebiete, die mich faszinieren oder motivieren?
• In welchen Bereichen könnte Software als Problemlöser dienen?
• Welche alltäglichen Prozesse, Aufgaben oder Probleme könnten durch Software unterstützt oder vereinfacht werden?
• Welche Technologien oder Programmiersprachen möchte ich dabei vertiefen?

📧 Aufgabe: E-Mail an Herrn Franke

Senden Sie Ihre Überlegungen und Ideen als E-Mail an Herrn Franke. Schreiben Sie in die E-Mail:

• Ihre Interessen und mögliche Themenideen für das M2-Softwareprojekt
• Welche Wünsche oder Themen Sie sich für das kommende Semester noch wünschen
• Falls vorhanden: offene Fragen zum Modul oder zu Technologien, die Sie gerne lernen möchten

🚀 Minimal Viable Product (MVP)

Ein Minimal Viable Product (MVP) ist eine erste, lauffähige Version einer Software, die nur die wichtigsten Kernfunktionen enthält. Das Ziel ist es, schnell ein funktionierendes Produkt zu entwickeln, es zu testen und Feedback zu sammeln, bevor viel Zeit in zusätzliche Features investiert wird.

Weitere Informationen zum MVP finden Sie hier:
https://t2informatik.de/wissen-kompakt/minimum-viable-product/

🔗 Weiterführender Artikel

Guter Überblick: Überblick über Vorgehensmodelle der Softwareentwicklung

https://www.scnsoft.de/blog/vorgehensmodelle-der-softwareentwicklung

📊 Anforderungsanalyse

Eine klare Anforderungsanalyse ist entscheidend für den Erfolg eines Softwareprojekts. Sie legt fest, was das Projekt können muss, welche Ziele verfolgt werden und welche Rahmenbedingungen gelten. Planen Sie daher ausreichend Zeit ein, um Anforderungen sauber zu definieren und mit Ihrer Gruppe abzusprechen.

⚡ Agile Methoden

Agile Methoden sind Vorgehensweisen in der Softwareentwicklung, bei denen Projekte in kleinen, überschaubaren Schritten umgesetzt werden. Sie ermöglichen Flexibilität und kontinuierliches Feedback während der Entwicklung.

🔷 Scrum

Scrum ist ein agiles Framework, das in kurzen Entwicklungszyklen (Sprints) arbeitet. Teams reflektieren regelmäßig ihre Arbeit, um sich kontinuierlich zu verbessern.

✅ Vorteile von Scrum:

• Schnelles Feedback
• Klare Rollen (Product Owner, Scrum Master, Developer Team)
• Flexibilität bei Änderungen

🔷 Kanban

Kanban ist eine Methode zur Visualisierung von Aufgaben in Form von Karten auf einem Board. Sie hilft dabei, Arbeitsprozesse transparent zu machen und Engpässe schnell zu erkennen.

✅ Vorteile von Kanban:

• Übersicht über alle Aufgaben
• Flexibles Anpassen der Prioritäten
• Keine festen Zeitabschnitte wie bei Scrum

📺 Video: Scrum vs. Kanban im Vergleich

Feedback zur Veranstaltung

Ihr Feedback ist wichtig, um die Veranstaltung kontinuierlich zu verbessern und auf Ihre Bedürfnisse anzupassen.

Bitte nehmen Sie sich am Ende des Semesters ein paar Minuten Zeit und füllen Sie das Feedbackformular unter folgendem Link aus:

https://informatik-franke.de/lehre/sose/eis/feedback/fb.html

Vielen Dank für Ihre Teilnahme und Ihre Rückmeldungen!