Stil-Guide

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:

1. Überschrift (H2/H3): Klare, handlungsorientierte Bezeichnung (z. B. „Einen neuen Eintrag erstellen").
2. Kurzeinführung: 1–2 Sätze zum Zweck und Nutzen der Funktion.
3. Voraussetzungen: Benötigte Berechtigungen (z. B. „Nur für den Administrator") oder Vorbereitung.
4. 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.
5. Ergebnis: Kurze Beschreibung dessen, was nach Abschluss sichtbar ist.
6. 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