Stil-Guide

Stil-Guide für die SocialOffice-Dokumentation

Dieser Leitfaden sichert eine einheitliche, professionelle und inklusive Dokumentation.

1. 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.

2. 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:

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`	`keacgmkcjipbdcpfoobecgkhfhffodhi`
Schlüsselwörter	Fett	Berechtigungen, Konfiguration
Code-Blöcke	Syntax-Highlighting	<syntaxhighlight lang="json">...</syntaxhighlight>

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. 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. Datei:Logo.png).

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

Struktur: Spalten für Feld, Wert und Beschreibung.
Lesbarkeit: Die erste Spalte (Feldname) wird fett markiert.
Inhalt: Technische Werte (IDs, URLs) in Backticks 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.
- 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 oder passiert.
Siehe auch: Liste relevanter verwandter Themen als interne Links.

Beispielstruktur für einen Eintrag: == Einen neuen Eintrag erstellen == Mit dieser Funktion fügen Sie einen neuen Datensatz in die Datenbank 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. # Bestätigen Sie mit <code>Speichern</code>. '''Ergebnis:''' Der neue Eintrag erscheint in der Übersicht und ist für andere Nutzer sichtbar. '''Siehe auch:''' [[Einträge bearbeiten]], [[Einträge löschen]]