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:
- Ü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
Backticksgesetzt. - Wichtige Entscheidungen oder Alternativen werden in einem eigenen Absatz oder einer Hinweis-Box erklärt.
- Ergebnis: Kurze Beschreibung dessen, was nach Abschluss sichtbar ist.
- Fehler & Troubleshooting (Optional): Falls die Funktion fehleranfällig ist, listen Sie hier häufige Fehlermeldungen und deren Lösung auf.
- 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
Backtickssetzen.
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.