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.
• 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 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. Fehler & Troubleshooting (Optional): Falls die Funktion fehleranfällig ist, listen Sie hier häufige Fehlermeldungen und deren Lösung auf.
7. 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. '''Fehler & Troubleshooting:''' * ''Fehlermeldung "Speichern fehlgeschlagen":'' Prüfen Sie, ob alle Pflichtfelder ausgefüllt sind. '''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	keacgmkcjipbdcpfoobecgkhfhffodhi
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. Datei:Logo.png).
• 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 Backticks 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.