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 feste Systembegriffe (z. B. Benutzer, 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") im allgemeinen Sprachgebrauch.
- Feste Systembegriffe: Begriffe, die als technische Rollen oder feste Modulnamen definiert sind, werden nicht angepasst.
- Beispiel 1: Der Begriff Benutzer (als Datenbank-Objekt oder Rolle) bleibt immer „Benutzer".
- Beispiel 2: Der Modulname Hauptmodul Mitarbeiter bleibt immer „Mitarbeiter".
- Falsch: „Benutzende", „Mitarbeitende" (wenn es sich um den festen Begriff handelt).
- Richtig (allgemein): „Die Person, die das System nutzt" oder „Das Team" (wenn kein fester Begriff gemeint ist).
4. Terminologie
Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen. Achtung: Feste Systembegriffe (siehe Abschnitt 3) haben Vorrang vor dieser Tabelle.
| Begriff | Verwenden | Nicht verwenden | Anmerkung |
|---|---|---|---|
| Person | Nutzer / Person | User, Account | Im allgemeinen Text. |
| Rolle (System) | Benutzer | User, Account, Benutzer (technisch) | Fester Systembegriff: Nie anpassen! |
| Rolle (Modul) | Mitarbeiter | Kunden, Fälle | Fester Modulname: "Hauptmodul Mitarbeiter" nie ändern. |
| 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:
- Überschrift