Stil-Guide: Unterschied zwischen den Versionen

← Zum vorherigen Versionsunterschied Zum nächsten Versionsunterschied →

Version vom 4. Mai 2026, 15:32 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.
Visuelle Unterstützung: Nutzen Sie Screenshots, um Texte zu entlasten.

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 Funktionsbezeichnungen (z. B. 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").
Technische Begriffe: Feste Rollenbezeichnungen wie Administrator werden nicht grammatikalisch angepasst, da sie spezifische technische Funktionen definieren.

4. Terminologie

Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen:

Begriff	Verwenden	Nicht verwenden
Person	Nutzer / Person	User, Account, Benutzer (technisch)
Rolle	Klienten	Kunden, Fälle
Daten	Eintrag	Datensatz, Record
Baustein	Modul	Feature, Komponente
Bereich	Administration	Admin-Bereich, Settings
Personenkreis	Mitarbeitende	Mitarbeiter, Personal
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 (H2/H3): Klare, handlungsorientierte Bezeichnung (z. B. „Einen neuen Eintrag erstellen").
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 Backticks 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.
Siehe auch: Liste relevanter verwandter Themen als interne Links.

Beispielstruktur: == 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. '''Siehe auch:''' [[Einträge bearbeiten]], [[Einträge löschen]]

6. Formatierung & Syntax

Konsistente Darstellung je nach Inhaltstyp während des Schreibens:

Typ	Formatierung	Beispiel
Menüpunkte	`Backticks`	`Administration`, `Weiteres`
Befehle	`Code-Block`	`gpupdate /force`
Dateinamen	`Backticks`	`policies.json`
URLs	Markdown-Link	[Linktext](https://...)
IDs / Keys	`Code-Block`

@@ Zeile 1: / Zeile 1: @@
 == Stil-Guide für die SocialOffice-Dokumentation ==
-Dieser Leitfaden sichert eine einheitliche, professionelle und inklusive Dokumentation.
+Dieser Leitfaden sichert eine einheitliche, professionelle und inklusive Dokumentation. Er folgt dem natürlichen Arbeitsfluss beim Erstellen von Einträgen.
-=== 1. Anrede & Sprache ===
+=== 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.
+* '''Visuelle Unterstützung:''' Nutzen Sie Screenshots, um Texte zu entlasten.
+=== 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 Funktionsbezeichnungen (z. B. Administrator) bleiben in ihrer technischen Schreibweise unverändert.
+* '''Ausnahmen:''' Technische Befehle, Code-Schnipsel und Funktionsbezeichnungen (z. B. '''Administrator''') bleiben in ihrer technischen Schreibweise unverändert.
-=== 2. Gendergerechte Sprache ===
+=== 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").
 * '''Technische Begriffe:''' Feste Rollenbezeichnungen wie '''Administrator''' werden nicht grammatikalisch angepasst, da sie spezifische technische Funktionen definieren.
-=== 3. Formatierung & Syntax ===
-Konsistente Darstellung je nach Inhaltstyp:
-{| 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>
-|}
 === 4. Terminologie ===
@@ Zeile 60: / Zeile 46: @@
 |}
-=== 5. Bilder & Screenshots ===
+=== 5. Aufbau eines Eintrags ===
-* '''Platzierung:''' Das Bild folgt erst, nachdem es im Fließtext erwähnt wurde.
+Jeder Eintrag folgt diesem Standard-Aufbau, um die Auffindbarkeit und Verständlichkeit zu maximieren:
-* '''Beschriftung:''' Jedes Bild benötigt eine klare, beschreibende Bildunterschrift.
-* '''Dateiname:''' Konsistente Benennung (z. B. <code>Datei:Logo.png</code>).
-=== 6. Interne Verweise ===
-* '''Konsistenz:''' Verlinkungen müssen einheitlich aufgebaut sein.
-* '''Prüfung:''' Vor dem Veröffentlichen sicherstellen, dass keine „Rot-Links" (fehlende Seiten) vorhanden sind.
-=== 7. Tabellen ===
+# '''Überschrift (H2/H3):''' Klare, handlungsorientierte Bezeichnung (z. B. „Einen neuen Eintrag erstellen").
-* '''Struktur:''' Spalten für Feld, Wert und Beschreibung.
+# '''Kurzeinführung:''' 1–2 Sätze zum Zweck und Nutzen der Funktion.
-* '''Lesbarkeit:''' Die erste Spalte (Feldname) wird '''fett''' markiert.
+# '''Voraussetzungen:''' Benötigte Berechtigungen (z. B. „Nur für den '''Administrator'''") oder Vorbereitung.
-* '''Inhalt:''' Technische Werte (IDs, URLs) in <code>Backticks</code> setzen.
-=== 8. Warnhinweise & Hinweise ===
-* Verwendung konsistenter Boxen-Styles für Warnungen, Tipps und wichtige Hinweise, um diese visuell hervorzuheben.
-=== 9. Aufbau eines Eintrags ===
-Jeder Eintrag zu einer Funktion, einem Modul oder einem Prozess folgt diesem Standard-Aufbau, um die Auffindbarkeit und Verständlichkeit zu maximieren:
-# '''Überschrift (H2/H3):''' Klare, handlungsorientierte Bezeichnung der Funktion (z. B. „Einen neuen Eintrag erstellen").
-# '''Kurzeinführung:''' 1–2 Sätze, die den Zweck der Funktion und den Nutzen für den Anwender erklären.
-# '''Voraussetzungen:''' Benötigte Berechtigungen (z. B. „Nur für den '''Administrator''' verfügbar") oder notwendige Vorbereitungsschritte.
 # '''Schritt-für-Schritt-Anleitung:'''
 #* Nummerierte Liste für sequenzielle Schritte.
@@ Zeile 88: / Zeile 57: @@
 #* 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 oder passiert.
+# '''Ergebnis:''' Kurze Beschreibung dessen, was nach Abschluss sichtbar ist.
 # '''Siehe auch:''' Liste relevanter verwandter Themen als interne Links.
-'''Beispielstruktur für einen Eintrag:'''
+'''Beispielstruktur:'''
 <nowiki>
 == Einen neuen Eintrag erstellen ==
-Mit dieser Funktion fügen Sie einen neuen Datensatz in die Datenbank hinzu.
+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 erforderlichen Daten in die Felder ein.
+# Geben Sie die Daten in die Felder ein.
 # Bestätigen Sie mit <code>Speichern</code>.
-'''Ergebnis:''' Der neue Eintrag erscheint in der Übersicht und ist für andere Nutzer sichtbar.
+'''Ergebnis:''' Der Eintrag erscheint in der Übersicht.
 '''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