Softwaredokumentation#

Eine gute Dokumentation ist genauso wichtig wie der Code selbst – sie ermöglicht Wartung, Erweiterung und Übergabe von Software an andere Entwickler oder Anwender.

Arten der Dokumentation#

          Softwaredokumentation
                   │
      ┌────────────┼────────────┐
      ▼            ▼            ▼
Entwickler-    Anwender-    Technische
dokumentation  dokumentation  Dokumentation
(intern)       (extern)       (Architektur)

Entwicklerdokumentation (interne Dokumentation)#

Richtet sich an Entwickler, die den Code warten, erweitern oder debuggen müssen.

Code-Kommentare#

# Einzeiliger Kommentar – kurze Erklärung einer Zeile
x = x + 1  # Zähler erhöhen

"""
Mehrzeiliger Kommentar (Docstring):
Beschreibt eine Funktion oder Klasse ausführlich.
"""

def berechne_mehrwertsteuer(netto: float, steuersatz: float = 0.19) -> float:
    """
    Berechnet den Bruttobetrag inkl. Mehrwertsteuer.

    Parameter:
        netto (float):      Nettobetrag in Euro
        steuersatz (float): MwSt-Satz als Dezimalzahl (Standard: 0.19 = 19%)

    Rückgabe:
        float: Bruttobetrag in Euro

    Beispiel:
        >>> berechne_mehrwertsteuer(100)
        119.0
    """
    return netto * (1 + steuersatz)

Was gehört in einen guten Kommentar?#

SinnvollÜberflüssig
Warum etwas so gemacht wirdWas offensichtlich im Code steht
Erklärung komplexer Algorithmenx = x + 1 # x wird um 1 erhöht
Dokumentation von Parametern/RückgabenJede einzelne Zeile kommentieren
Bekannte Einschränkungen / TODOVeraltete Kommentare (schlimmer als keine!)

Changelog / Versionierung#

Dokumentiert was wann von wem geändert wurde:

# Changelog

## Version 2.1.0 – 2026-03-15
### Hinzugefügt
- Exportfunktion für CSV-Dateien
### Geändert
- Datenbankverbindung auf PostgreSQL umgestellt
### Behoben
- Fehler bei Leerzeichen in Benutzernamen (#42)

## Version 2.0.0 – 2026-01-10
### Hinzugefügt
- Benutzerrollen: Admin, Editor, Viewer

Anwenderdokumentation (externe Dokumentation)#

Richtet sich an Endanwender – ohne Programmierkenntnisse verständlich.

Inhalte#

BestandteilBeschreibung
EinleitungWas ist das Programm? Wofür wird es verwendet?
SystemvoraussetzungenBetriebssystem, Hardware, Installationsvoraussetzungen
InstallationSchritt-für-Schritt-Anleitung
Erste SchritteSchnelleinstieg, typische Anwendungsszenarien
FunktionsbeschreibungAlle Menüs, Buttons, Optionen erklärt
Fehlermeldungen & LösungenHäufige Probleme und Abhilfe (FAQ)
GlossarErklärung von Fachbegriffen
Kontakt / SupportAn wen wende ich mich bei Problemen?

Sprache & Stil#

  • Einfache Sprache – keine Fachbegriffe ohne Erklärung
  • Aktiv formulieren: „Klicken Sie auf…" statt „Es wird geklickt…"
  • Screenshots zur Veranschaulichung
  • Schritt-für-Schritt statt Fließtext
  • Aus Nutzersicht schreiben (Was will der Nutzer erreichen?)

Technische Dokumentation (Systemdokumentation)#

Richtet sich an Systemadministratoren und Architekten.

Inhalte#

BestandteilBeschreibung
SystemarchitekturÜbersicht aller Komponenten, Schnittstellen, Abhängigkeiten
DatenbankschemaERM, Relationenschema, Tabellenstruktur
API-DokumentationEndpunkte, Parameter, Rückgabewerte, Authentifizierung
DeploymentWie wird das System installiert/betrieben?
SicherheitskonzeptZugriffsrechte, Verschlüsselung, Backup
NetzwerkplanWie ist das System eingebunden?

Vergleich der Dokumentationstypen#

EntwicklerdokumentationAnwenderdokumentationTechnische Doku
ZielgruppeEntwicklerEndanwenderAdmins / Architekten
SpracheTechnischEinfachTechnisch
FokusCode, Logik, AlgorithmenBedienung, FunktionenSystem, Infrastruktur
FormatKommentare, README, DocstringsHandbuch, PDF, WikiDiagramme, Spezifikationen
WannWährend der EntwicklungNach FertigstellungProjekt- und Betriebsphase

README – Die wichtigste Entwicklerdoku#

Eine README.md ist das erste, was ein neuer Entwickler liest:

# Projektname

Kurze Beschreibung: Was macht das Projekt?

## Voraussetzungen
- Python 3.10+
- PostgreSQL 14+

## Installation
1. Repository klonen: `git clone https://github.com/...`
2. Abhängigkeiten installieren: `pip install -r requirements.txt`
3. Konfiguration anpassen: `.env.example` → `.env`
4. Starten: `python main.py`

## Verwendung
Kurze Beispiele zur Nutzung...

## Struktur
projekt/
├── main.py        # Einstiegspunkt
├── db/            # Datenbankmodule
└── tests/         # Unittests

## Lizenz
MIT License

Dokumentationswerkzeuge#

ToolTypBeschreibung
Markdown (.md)TextformatEinfach, gut lesbar, für README/Wikis
Javadoc / DocstringCode-KommentareAutomatisch aus Quellcode generiert
ConfluenceWikiUnternehmens-Wiki für Team-Dokumentation
Swagger / OpenAPIAPI-DokuStandardformat für REST-API-Dokumentation
draw.io / VisioDiagrammeArchitektur- und Ablaufdiagramme

Prüfungsbeispiele#

„Was ist der Unterschied zwischen Anwenderdokumentation und Entwicklerdokumentation?"

→ Anwenderdokumentation richtet sich an Endnutzer ohne Programmierkenntnisse – erklärt die Bedienung der Software. Entwicklerdokumentation richtet sich an Programmierer – erklärt Code, Logik, Schnittstellen und interne Abläufe.

„Warum sind Kommentare im Quellcode wichtig?"

→ Sie ermöglichen anderen Entwicklern (und dem Autor selbst nach Wochen), den Code schnell zu verstehen, zu warten und zu erweitern – ohne den gesamten Algorithmus neu durchdenken zu müssen.

„Ein Kollege übernimmt dein Projekt. Welche Dokumentation ist am wichtigsten?"

→ Eine gute README.md mit Installationsanleitung, Projektstruktur und Kurzbeschreibung – ergänzt durch Code-Kommentare für komplexe Stellen und ein Datenbankschema falls eine Datenbank genutzt wird.

Siehe auch#

  • uml — UML-Diagramme als Teil der technischen Dokumentation (Aktivitätsdiagramme, Klassendiagramme)
  • datenformate — Swagger/OpenAPI nutzt JSON/YAML zur API-Dokumentation
  • [[../08_datenbanken/erm]] — Datenbankschema als Bestandteil der technischen Dokumentation
  • [[../09_projektmanagement/agile_methoden]] — Dokumentation in agilen Projekten (Definition of Done)
  • [[../10_recht/lizenzen]] — Lizenzen im README-Abschnitt (MIT, GPL, etc.)

Ressourcen#

Backward Datenformate Testverfahren Forward