Zum Inhalt springen

Stil-Guide: Unterschied zwischen den Versionen

Aus SocialOffice Dokumentation
← Zum vorherigen Versionsunterschied
VisuellWikitext
Keine Bearbeitungszusammenfassung
Keine Bearbeitungszusammenfassung
 
(3 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
== Stil-Guide für die SocialOffice-Dokumentation ==
== Stil-Guide für die SocialOffice-Dokumentation ==


Dieser Leitfaden sichert eine einheitliche, professionelle und inklusive Dokumentation.
Dieser Leitfaden sichert eine einheitliche, professionelle und inklusive Dokumentation. Er folgt dem natürlichen Arbeitsfluss beim Erstellen von Einträgen.


=== 1. Anrede & Sprache ===
=== 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.
* '''Form:''' Durchgehend formelle '''„Sie"'''-Form.
** ''Richtig:'' „Wählen Sie das Modul aus."
** ''Richtig:'' „Wählen Sie das Modul aus."
** ''Falsch:'' „Wähle 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.
* '''Fachbegriffe:''' Technische Befehle, Code-Schnipsel und fest definierte Rollenbezeichnungen (z. B. '''Administrator''', '''Benutzer''') bleiben in ihrer originalen Schreibweise.


=== 2. Gendergerechte Sprache ===
=== 3. Gendergerechte Sprache ===
* '''Prinzip:''' Alle Geschlechter sollen angesprochen werden, ohne den Lesefluss zu stören.
* '''Prinzip:''' Alle Geschlechter sollen angesprochen werden, ohne den Lesefluss zu stören.
* '''Umsetzung:''' Bevorzugt werden neutrale Formulierungen (z. B. „die nutzende Person", „das Team").
* '''Umsetzung:''' Im allgemeinen Sprachgebrauch werden neutrale Formulierungen bevorzugt (z. B. „die nutzende Person", „das Team").
* '''Technische Begriffe:''' Feste Rollenbezeichnungen wie '''Administrator''' werden nicht grammatikalisch angepasst, da sie spezifische technische Funktionen definieren.
* '''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.


=== 3. Formatierung & Syntax ===
=== 4. Terminologie ===
Konsistente Darstellung je nach Inhaltstyp:
Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Typ !! Formatierung !! Beispiel
! Begriff !! Verwenden !! Nicht verwenden !! Anmerkung
|-
| Person (allgemein) || Nutzer / Person || User, Account || Im allgemeinen Text.
|-
|-
| '''Menüpunkte''' || <code>Backticks</code> || <code>Administration</code>, <code>Weiteres</code>
| Rolle (System) || Benutzer || User, Account || Fester Systembegriff.
|-
|-
| '''Befehle''' || <code>Code-Block</code> || <code>gpupdate /force</code>
| Rolle (Modul) || Mitarbeiter || Kunden, Fälle || Fester Modulname ("Hauptmodul Mitarbeiter").
|-
|-
| '''Dateinamen''' || <code>Backticks</code> || <code>policies.json</code>
| Daten || Eintrag || Datensatz, Record ||  
|-
|-
| '''URLs''' || [[Markdown-Link]] || [Linktext](https://...)
| Baustein || Modul || Feature, Komponente ||  
|-
|-
| '''IDs / Keys''' || <code>Code-Block</code> || <code>keacgmkcjipbdcpfoobecgkhfhffodhi</code>
| Bereich || Administration || Admin-Bereich, Settings ||  
|-
|-
| '''Schlüsselwörter''' || '''Fett''' || '''Berechtigungen''', '''Konfiguration'''
| Leiste || Toolbar || Werkzeugleiste ||  
|-
|-
| '''Code-Blöcke''' || Syntax-Highlighting || <syntaxhighlight lang="json">...</syntaxhighlight>
| Bereich || Navigation || Menü, Sidebar ||  
|}
|}


=== 4. Terminologie ===
=== 5. Aufbau eines Eintrags ===
Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen:
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''' verfügbar") 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 <code>Backticks</code> gesetzt.
#* 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:'''
<nowiki>
== 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]]
</nowiki>
 
=== 6. Formatierung & Syntax ===
Konsistente Darstellung je nach Inhaltstyp während des Schreibens:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Begriff !! Verwenden !! Nicht verwenden
! Typ !! Formatierung !! Beispiel
|-
|-
| Person || Nutzer / Person || User, Account, Benutzer (technisch)
| '''Menüpunkte''' || <code>Backticks</code> || <code>Administration</code>, <code>Weiteres</code>
|-
|-
| Rolle || Klienten || Kunden, Fälle
| '''Befehle''' || <code>Code-Block</code> || <code>gpupdate /force</code>
|-
|-
| Daten || Eintrag || Datensatz, Record
| '''Dateinamen''' || <code>Backticks</code> || <code>policies.json</code>
|-
|-
| Baustein || Modul || Feature, Komponente
| '''URLs''' || [[Markdown-Link]] || [Linktext](https://...)
|-
|-
| Bereich || Administration || Admin-Bereich, Settings
| '''IDs / Keys''' || <code>Code-Block</code> || <code>keacgmkcjipbdcpfoobecgkhfhffodhi</code>
|-
|-
| Personenkreis || Mitarbeitende || Mitarbeiter, Personal
| '''Schlüsselwörter''' || '''Fett''' || '''Berechtigungen''', '''Konfiguration'''
|-
|-
| Leiste || Toolbar || Werkzeugleiste
| '''Code-Blöcke''' || Syntax-Highlighting || <syntaxhighlight lang="json">...</syntaxhighlight>
|-
| Bereich || Navigation || Menü, Sidebar
|}
|}


=== 5. Bilder & Screenshots ===
=== 7. Bilder & Screenshots ===
* '''Platzierung:''' Das Bild folgt erst, nachdem es im Fließtext erwähnt wurde.
* '''Platzierung:''' Das Bild folgt erst, nachdem es im Fließtext erwähnt wurde.
* '''Beschriftung:''' Jedes Bild benötigt eine klare, beschreibende Bildunterschrift.
* '''Beschriftung:''' Jedes Bild benötigt eine klare, beschreibende Bildunterschrift.
* '''Dateiname:''' Konsistente Benennung (z. B. <code>Datei:Logo.png</code>).
* '''Dateiname:''' Konsistente Benennung (z. B. <code>Datei:Logo.png</code>).
* '''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.


=== 6. Interne Verweise ===
=== 8. Tabellen ===
* '''Konsistenz:''' Verlinkungen müssen einheitlich aufgebaut sein.
* '''Prüfung:''' Vor dem Veröffentlichen sicherstellen, dass keine „Rot-Links" (fehlende Seiten) vorhanden sind.
 
=== 7. Tabellen ===
* '''Struktur:''' Spalten für Feld, Wert und Beschreibung.
* '''Struktur:''' Spalten für Feld, Wert und Beschreibung.
* '''Lesbarkeit:''' Die erste Spalte (Feldname) wird '''fett''' markiert.
* '''Lesbarkeit:''' Die erste Spalte (Feldname) wird '''fett''' markiert.
* '''Inhalt:''' Technische Werte (IDs, URLs) in <code>Backticks</code> setzen.
* '''Inhalt:''' Technische Werte (IDs, URLs) in <code>Backticks</code> setzen.


=== 8. Warnhinweise & Hinweise ===
=== 9. Warnhinweise & Hinweise ===
* Verwendung konsistenter Boxen-Styles für Warnungen, Tipps und wichtige Hinweise, um diese visuell hervorzuheben.
* Verwendung konsistenter Boxen-Styles für Warnungen, Tipps und wichtige Hinweise, um diese visuell hervorzuheben.


=== 9. Aufbau eines Eintrags ===
=== 10. Interne Verweise & Prüfung ===
Jeder Eintrag zu einer Funktion, einem Modul oder einem Prozess folgt diesem Standard-Aufbau, um die Auffindbarkeit und Verständlichkeit zu maximieren:
* '''Konsistenz:''' Verlinkungen müssen einheitlich aufgebaut sein.
 
* '''Prüfung vor Veröffentlichung:'''
# '''Überschrift (H2/H3):''' Klare, handlungsorientierte Bezeichnung der Funktion (z. B. „Einen neuen Eintrag erstellen").
** Sicherstellen, dass keine „Rot-Links" (fehlende Seiten) vorhanden sind.
# '''Kurzeinführung:''' 1–2 Sätze, die den Zweck der Funktion und den Nutzen für den Anwender erklären.
** Prüfen, ob alle Schritte für einen Laien nachvollziehbar sind.
# '''Voraussetzungen:''' Benötigte Berechtigungen (z. B. „Nur für den '''Administrator''' verfügbar") oder notwendige Vorbereitungsschritte.
** Kontrolle auf einheitliche Terminologie und „Sie"-Form.
# '''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 <code>Backticks</code> gesetzt.
#* Wichtige Entscheidungen oder Alternativen werden in einem eigenen Absatz oder einer Hinweis-Box erklärt.
# '''Ergebnis:''' Kurze Beschreibung dessen, was nach Abschluss sichtbar ist oder passiert.
# '''Siehe auch:''' Liste relevanter verwandter Themen als interne Links.
 
'''Beispielstruktur für einen Eintrag:'''
<nowiki>
== Einen neuen Eintrag erstellen ==
 
Mit dieser Funktion fügen Sie einen neuen Datensatz in die Datenbank hinzu.
 
'''Voraussetzungen:''' Sie benötigen die Berechtigung „Einträge bearbeiten".
 
# Klicken Sie im Menü auf <code>Neuer Eintrag</code>.
# Geben Sie die erforderlichen Daten in die Felder ein.
# Bestätigen Sie mit <code>Speichern</code>.
 
'''Ergebnis:''' Der neue Eintrag erscheint in der Übersicht und ist für andere Nutzer sichtbar.


'''Siehe auch:''' [[Einträge bearbeiten]], [[Einträge löschen]]
=== 11. Wartung & Aktualität ===
</nowiki>
* '''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.

Aktuelle Version vom 4. Mai 2026, 15:49 Uhr

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.
Abgerufen von „https://doku.socialoffice.ch/index.php?title=Stil-Guide&oldid=493“