Stil-Guide: Unterschied zwischen den Versionen

← Zum vorherigen Versionsunterschied Zum nächsten Versionsunterschied →

Version vom 4. Mai 2026, 15:47 Uhr

Stil-Guide für die SocialOffice-Dokumentation

Dieser Leitfaden sichert eine einheitliche, professionelle und inklusive Dokumentation. Er folgt dem natürlichen Arbeitsfluss beim Erstellen von Einträgen.

1. Zielgruppe & Verständlichkeit

Wichtig: Die Dokumentation richtet sich primär an Anwender ohne technisches Vorwissen.

Keine Fachsprache: Vermeiden Sie IT-Jargon (z. B. „API", „Backend", „Server"), es sei denn, er ist zwingend notwendig. Erklären Sie Fachbegriffe bei der ersten Nennung kurz.
Konkret statt abstrakt: Beschreiben Sie, was der Nutzer sieht („Ihre Änderung wird gespeichert"), nicht was im Hintergrund passiert.
Keine Annahmen: Gehen Sie nicht davon aus, dass der Nutzer weiß, wo ein Menü ist. Beschreiben Sie jeden Klick explizit.
Fehlervermeidung: Erklären Sie, was bei falschen Schritten passiert und wie man korrigiert.
Suchbarkeit (SEO): Formulieren Sie Überschriften als konkrete Aufgaben oder Fragen (z. B. „Wie exportiere ich eine Liste?" statt „Export-Funktion"). So finden Nutzer den Eintrag leichter über die Suchleiste.

2. Anrede & Sprache

Form: Durchgehend formelle „Sie"-Form.
- Richtig: „Wählen Sie das Modul aus."
- Falsch: „Wähle das Modul aus."
Ausnahmen: Technische Befehle, Code-Schnipsel und feste Systembegriffe (z. B. Benutzer, Administrator) bleiben in ihrer technischen Schreibweise unverändert.

3. Gendergerechte Sprache

Prinzip: Alle Geschlechter sollen angesprochen werden, ohne den Lesefluss zu stören.
Umsetzung: Bevorzugt werden neutrale Formulierungen (z. B. „die nutzende Person", „das Team") im allgemeinen Sprachgebrauch.
Feste Systembegriffe: Begriffe, die als technische Rollen oder feste Modulnamen definiert sind, werden nicht angepasst.
- Beispiel 1: Der Begriff Benutzer (als Datenbank-Objekt oder Rolle) bleibt immer „Benutzer".
- Beispiel 2: Der Modulname Hauptmodul Mitarbeiter bleibt immer „Mitarbeiter".
- Falsch: „Benutzende", „Mitarbeitende" (wenn es sich um den festen Begriff handelt).
- Richtig (allgemein): „Die Person, die das System nutzt" oder „Das Team" (wenn kein fester Begriff gemeint ist).

4. Terminologie

Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen. Achtung: Feste Systembegriffe (siehe Abschnitt 3) haben Vorrang vor dieser Tabelle.

Begriff	Verwenden	Nicht verwenden	Anmerkung
Person	Nutzer / Person	User, Account	Im allgemeinen Text.
Rolle (System)	Benutzer	User, Account, Benutzer (technisch)	Fester Systembegriff: Nie anpassen!
Rolle (Modul)	Mitarbeiter	Kunden, Fälle	Fester Modulname: "Hauptmodul Mitarbeiter" nie ändern.
Daten	Eintrag	Datensatz, Record
Baustein	Modul	Feature, Komponente
Bereich	Administration	Admin-Bereich, Settings
Leiste	Toolbar	Werkzeugleiste
Bereich	Navigation	Menü, Sidebar

5. Aufbau eines Eintrags

Jeder Eintrag folgt diesem Standard-Aufbau, um die Auffindbarkeit und Verständlichkeit zu maximieren:

Überschrift

@@ Zeile 15: / Zeile 15: @@
 ** ''Richtig:'' „Wählen Sie das Modul aus."
 ** ''Falsch:'' „Wähle das Modul aus."
-* '''Ausnahmen:''' Technische Befehle, Code-Schnipsel und Funktionsbezeichnungen (z. B. '''Administrator''') bleiben in ihrer technischen Schreibweise unverändert.
+* '''Ausnahmen:''' Technische Befehle, Code-Schnipsel und '''feste Systembegriffe''' (z. B. '''Benutzer''', '''Administrator''') bleiben in ihrer technischen Schreibweise unverändert.
 === 3. Gendergerechte Sprache ===
 * '''Prinzip:''' Alle Geschlechter sollen angesprochen werden, ohne den Lesefluss zu stören.
-* '''Umsetzung:''' Bevorzugt werden neutrale Formulierungen (z. B. „die nutzende Person", „das Team").
+* '''Umsetzung:''' Bevorzugt werden neutrale Formulierungen (z. B. „die nutzende Person", „das Team") im allgemeinen Sprachgebrauch.
-* '''Technische Begriffe:''' Feste Rollenbezeichnungen wie '''Administrator''' werden nicht grammatikalisch angepasst, da sie spezifische technische Funktionen definieren.
+* '''Feste Systembegriffe:''' Begriffe, die als technische Rollen oder feste Modulnamen definiert sind, werden '''nicht''' angepasst.
+** '''Beispiel 1:''' Der Begriff '''Benutzer''' (als Datenbank-Objekt oder Rolle) bleibt immer „Benutzer".
+** '''Beispiel 2:''' Der Modulname '''Hauptmodul Mitarbeiter''' bleibt immer „Mitarbeiter".
+** ''Falsch:'' „Benutzende", „Mitarbeitende" (wenn es sich um den festen Begriff handelt).
+** ''Richtig (allgemein):'' „Die Person, die das System nutzt" oder „Das Team" (wenn kein fester Begriff gemeint ist).
 === 4. Terminologie ===
-Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen:
+Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen. '''Achtung:''' Feste Systembegriffe (siehe Abschnitt 3) haben Vorrang vor dieser Tabelle.
 {| class="wikitable"
 |-
-! Begriff !! Verwenden !! Nicht verwenden
+! Begriff !! Verwenden !! Nicht verwenden !! Anmerkung
 |-
-| Person || Nutzer / Person || User, Account, Benutzer (technisch)
+| Person || Nutzer / Person || User, Account || Im allgemeinen Text.
 |-
-| Rolle || Klienten || Kunden, Fälle
+| Rolle (System) || '''Benutzer''' || User, Account, Benutzer (technisch) || '''Fester Systembegriff: Nie anpassen!'''
 |-
-| Daten || Eintrag || Datensatz, Record
+| Rolle (Modul) || '''Mitarbeiter''' || Kunden, Fälle || '''Fester Modulname: "Hauptmodul Mitarbeiter" nie ändern.'''
 |-
-| Baustein || Modul || Feature, Komponente
+| Daten || Eintrag || Datensatz, Record ||
 |-
-| Bereich || Administration || Admin-Bereich, Settings
+| Baustein || Modul || Feature, Komponente ||
 |-
-| Personenkreis || Mitarbeitende || Mitarbeiter, Personal
+| Bereich || Administration || Admin-Bereich, Settings ||
 |-
-| Leiste || Toolbar || Werkzeugleiste
+| Leiste || Toolbar || Werkzeugleiste ||
 |-
-| Bereich || Navigation || Menü, Sidebar
+| Bereich || Navigation || Menü, Sidebar ||
 |}
@@ Zeile 49: / Zeile 53: @@
 Jeder Eintrag folgt diesem Standard-Aufbau, um die Auffindbarkeit und Verständlichkeit zu maximieren:
-# '''Überschrift (H2/H3):''' Klare, handlungsorientierte Bezeichnung (z. B. „Einen neuen Eintrag erstellen").
+# '''Überschrift
-# '''Kurzeinführung:''' 1–2 Sätze zum Zweck und Nutzen der Funktion.
-# '''Voraussetzungen:''' Benötigte Berechtigungen (z. B. „Nur für den '''Administrator'''") oder Vorbereitung.
-# '''Schritt-für-Schritt-Anleitung:'''
-#* Nummerierte Liste für sequenzielle Schritte.
-#* Jeder Schritt beginnt mit einem Verb in der „Sie"-Form (z. B. „Klicken Sie auf...").
-#* Interne Elemente (Menüs, Buttons) werden in <code>Backticks</code> gesetzt.
-#* Wichtige Entscheidungen oder Alternativen werden in einem eigenen Absatz oder einer Hinweis-Box erklärt.
-# '''Ergebnis:''' Kurze Beschreibung dessen, was nach Abschluss sichtbar ist.
-# '''Fehler & Troubleshooting (Optional):''' Falls die Funktion fehleranfällig ist, listen Sie hier häufige Fehlermeldungen und deren Lösung auf.
-# '''Siehe auch:''' Liste relevanter verwandter Themen als interne Links.
-'''Beispielstruktur:'''
-<nowiki>
-== Einen neuen Eintrag erstellen ==
-Mit dieser Funktion fügen Sie einen neuen Datensatz hinzu.
-'''Voraussetzungen:''' Sie benötigen die Berechtigung „Einträge bearbeiten".
-# Klicken Sie im Menü auf <code>Neuer Eintrag</code>.
-# Geben Sie die Daten in die Felder ein.
-# Bestätigen Sie mit <code>Speichern</code>.
-'''Ergebnis:''' Der Eintrag erscheint in der Übersicht.
-'''Fehler & Troubleshooting:'''
-* ''Fehlermeldung "Speichern fehlgeschlagen":'' Prüfen Sie, ob alle Pflichtfelder ausgefüllt sind.
-'''Siehe auch:''' [[Einträge bearbeiten]], [[Einträge löschen]]
-</nowiki>
-=== 6. Formatierung & Syntax ===
-Konsistente Darstellung je nach Inhaltstyp während des Schreibens:
-{| class="wikitable"
-|-
-! Typ !! Formatierung !! Beispiel
-|-
-| '''Menüpunkte''' || <code>Backticks</code> || <code>Administration</code>, <code>Weiteres</code>
-|-
-| '''Befehle''' || <code>Code-Block</code> || <code>gpupdate /force</code>
-|-
-| '''Dateinamen''' || <code>Backticks</code> || <code>policies.json</code>
-|-
-| '''URLs''' || [[Markdown-Link]] || [Linktext](https://...)
-|-
-| '''IDs / Keys''' || <code>Code-Block</code> || <code>keacgmkcjipbdcpfoobecgkhfhffodhi</code>
-|-
-| '''Schlüsselwörter''' || '''Fett''' || '''Berechtigungen''', '''Konfiguration'''
-|-
-| '''Code-Blöcke''' || Syntax-Highlighting || <syntaxhighlight lang="json">...</syntaxhighlight>
-|}
-=== 7. Bilder & Screenshots ===
-* '''Platzierung:''' Das Bild folgt erst, nachdem es im Fließtext erwähnt wurde.
-* '''Beschriftung:''' Jedes Bild benötigt eine klare, beschreibende Bildunterschrift.
-* '''Dateiname:''' Konsistente Benennung (z. B. <code>Datei:Logo.png</code>).
-* '''Hinweis für Laien:''' Nutzen Sie Pfeile oder Markierungen auf Bildern, um den Fokus zu lenken.
-* '''Barrierefreiheit:''' Fügen Sie jedem Bild einen Alternativtext (Alt-Tag) hinzu, der den Inhalt beschreibt. Dies hilft Nutzern mit Sehschwäche und verbessert die Suche.
-=== 8. Tabellen ===
-* '''Struktur:''' Spalten für Feld, Wert und Beschreibung.
-* '''Lesbarkeit:''' Die erste Spalte (Feldname) wird '''fett''' markiert.
-* '''Inhalt:''' Technische Werte (IDs, URLs) in <code>Backticks</code> setzen.
-=== 9. Warnhinweise & Hinweise ===
-* Verwendung konsistenter Boxen-Styles für Warnungen, Tipps und wichtige Hinweise, um diese visuell hervorzuheben.
-=== 10. Interne Verweise & Prüfung ===
-* '''Konsistenz:''' Verlinkungen müssen einheitlich aufgebaut sein.
-* '''Prüfung vor Veröffentlichung:'''
-** Sicherstellen, dass keine „Rot-Links" (fehlende Seiten) vorhanden sind.
-** Prüfen, ob alle Schritte für einen Laien nachvollziehbar sind.
-** Kontrolle auf einheitliche Terminologie und „Sie"-Form.
-=== 11. Wartung & Aktualität ===
-* '''Versionshinweise:''' Wenn eine Funktion nur in einer bestimmten Software-Version verfügbar ist, kennzeichnen Sie dies deutlich (z. B. „Ab Version 2.1").
-* '''Aktualisierungspflicht:''' Bei Änderungen der Benutzeroberfläche (z. B. neue Menüstruktur) müssen betroffene Einträge innerhalb von 48 Stunden aktualisiert werden.
-* '''Veraltete Inhalte:''' Markieren Sie veraltete Anleitungen mit einem Hinweis-Box, bis sie ersetzt sind.