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."
• Fachbegriffe: Technische Befehle, Code-Schnipsel und fest definierte Rollenbezeichnungen (z. B. Administrator, Benutzer) bleiben in ihrer originalen Schreibweise.

3. Gendergerechte Sprache

• Prinzip: Alle Geschlechter sollen angesprochen werden, ohne den Lesefluss zu stören.
• Umsetzung: Im allgemeinen Sprachgebrauch werden neutrale Formulierungen bevorzugt (z. B. „die nutzende Person", „das Team").
• Systembegriffe: Feste Rollen und Modulnamen, die als technische Entitäten definiert sind, werden nicht angepasst.
  • Der Begriff Benutzer bleibt als Datenbank-Objekt unverändert.
  • Der Modulname Hauptmodul Mitarbeiter bleibt unverändert.
  • Der Rollenbegriff Administrator bleibt unverändert.

4. Terminologie

Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen.

Begriff	Verwenden	Nicht verwenden	Anmerkung
Person (allgemein)	Nutzer / Person	User, Account	Im allgemeinen Text.
Rolle (System)	Benutzer	User, Account	Fester Systembegriff.
Rolle (Modul)	Mitarbeiter	Kunden, Fälle	Fester Modulname ("Hauptmodul Mitarbeiter").
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:

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 verfügbar") 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.