Zum Inhalt springen

Stil-Guide: Unterschied zwischen den Versionen

Aus SocialOffice Dokumentation
Zum nächsten Versionsunterschied →
VisuellWikitext
Die Seite wurde neu angelegt: „= Stil-Guide für die SocialOffice-Dokumentation = Dieser Leitfaden dient allen Autoren und Redakteuren, um eine einheitliche, professionelle und inklusive Dokumentation zu gewährleisten. Er definiert Regeln für Sprache, Formatierung, Struktur und visuelle Elemente. __TOC__ *Letzte Aktualisierung: 04. Mai 2026* ---- == 1. 🎯 Anrede & Sprache == === Regel: Durchgehend "Sie"-Form === Die Dokumentation spricht den Nutzer höflich und professionell…“
 
Keine Bearbeitungszusammenfassung
Zeile 1: Zeile 1:
= Stil-Guide für die SocialOffice-Dokumentation =
== Stil-Guide für die SocialOffice-Dokumentation ==


Dieser Leitfaden dient allen Autoren und Redakteuren, um eine einheitliche, professionelle und inklusive Dokumentation zu gewährleisten. Er definiert Regeln für Sprache, Formatierung, Struktur und visuelle Elemente.
Dieser Leitfaden sichert eine einheitliche, professionelle und inklusive Dokumentation.


__TOC__
=== 1. 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.


*Letzte Aktualisierung: 04. Mai 2026*
=== 2. 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.


----
=== 3. Formatierung & Syntax ===
 
Konsistente Darstellung je nach Inhaltstyp:
== 1. 🎯 Anrede & Sprache ==
 
=== Regel: Durchgehend "Sie"-Form ===
Die Dokumentation spricht den Nutzer höflich und professionell an.
 
{| class="wikitable"
|-
! ✅ Richtig !! ❌ Falsch
|-
| "Wählen Sie das Modul aus" || "Wähle das Modul aus"
|-
| "Sie können Dateien anhängen" || "Du kannst Dateien anhängen"
|-
| "Öffnen Sie das Fenster" || "Öffne das Fenster"
|}
 
'''Ausnahmen:'''
* Technische Befehle/Commands bleiben in der Originalform (z. B. <code>gpupdate /force</code>)
* Menüpunkte werden in <code>Backticks</code> geschrieben (z. B. <code>Administration</code>)
 
----
 
== 2. 👥 Gendergerechte Sprache ==
 
Ziel ist es, alle Geschlechter gleichermaßen anzusprechen und sichtbar zu machen, ohne den Lesefluss unnötig zu stören. Wir verwenden eine '''kombinierte Strategie''' aus '''Neutrale Formulierungen''' (Priorität 1) und '''geschlechtsneutralen Bezeichnungen''' (Priorität 2).
 
=== A. Priorität 1: Neutrale Formulierungen (Empfohlen) ===
Versuchen Sie, geschlechtsspezifische Begriffe durch neutrale Umschreibungen zu ersetzen. Dies ist oft flüssiger zu lesen.
 
{| class="wikitable"
|-
! Statt (geschlechtsspezifisch) !! Nutzen (neutral) !! Beispiel im Text
|-
| '''Der Benutzer''' || '''Der Nutzer''' / '''Die Person''' || "Der '''Nutzer''' kann..." statt "Der Benutzer kann..."
|-
| '''Der Administrator''' || '''Die Verwaltung''' / '''Die Admin-Person''' || "Die '''Verwaltung''' erstellt..."
|-
| '''Der Kunde''' || '''Die Klientin / Der Klient''' || Im Modul "Klienten" ist "Klient" bereits neutral, aber "Die Person" ist oft besser.
|-
| '''Die Mitarbeiter''' || '''Das Team''' / '''Die Mitarbeitenden''' || "'''Die Mitarbeitenden''' können..."
|-
| '''Der Leser''' || '''Die Leserin / Der Leser''' (nur wenn nötig) || Besser: "'''Wer dies liest'''..."
|}
 
=== B. Priorität 2: Geschlechtsneutrale Bezeichnungen ===
Wenn eine neutrale Umschreibung nicht möglich ist oder der Begriff fest etabliert ist (z. B. in Datenbankfeldern), verwenden Sie '''geschlechtsneutrale Formen'''.
 
'''Empfohlene Form:''' '''Das Binnen-I''' oder '''Paarform''' (je nach Kontext).
*Hinweis: Für technische Dokumentation (Software-UI) ist oft das '''Binnen-I''' oder die '''Pluralform''' am besten lesbar.*
 
{| class="wikitable"
|-
! Situation !! Empfehlung !! Beispiel
|-
| '''Allgemeine Ansprache''' || '''Plural''' (oft am elegantesten) || "'''Die Nutzer''' können..." statt "Der Nutzer/Die Nutzerin"
|-
| '''Einzelne Person''' || '''Binnen-I''' (nur bei feststehenden Begriffen) || "Der '''Benutzer'''" (wenn "Nutzer" nicht passt) <br> ''Alternative:'' "Die '''Benutzende'''" (sehr inklusiv, aber oft schwer lesbar)
|-
| '''UI-Elemente / Felder''' || '''Original beibehalten''' || Wenn die Software "Benutzername" heißt, schreiben Sie "Benutzername".
|}
 
'''❌ Vermeiden:'''
* Schrägstriche (<code>Benutzer/in</code>) – stört den Lesefluss und Screenreader
* Doppelpunkte (<code>Benutzer:innen</code>) – in technischen Anleitungen oft zu unterbrechend
* Sternchen (<code>Benutzer*innen</code>) – kann in Code-Blöcken oder technischen Kontexten verwirrend wirken
 
=== C. Konkrete Anwendung im SocialOffice-Kontext ===
 
{| class="wikitable"
|-
! Begriff im System !! Empfehlung in der Doku !! Begründung
|-
| '''Benutzer''' || '''Nutzer''' oder '''Person''' || "Benutzer" klingt technisch; "Nutzer" ist menschlicher.
|-
| '''Mitarbeiter''' || '''Mitarbeitende''' || Inklusive aller Geschlechter.
|-
| '''Administrator''' || '''Admin-Person''' oder '''Verwaltung''' || Vermeidet "Der Administrator".
|-
| '''Klient''' || '''Klient''' (bleibt) || Der Begriff ist im Modul fest verankert und bereits relativ neutral.
|-
| '''Leser''' || '''Nutzer''' || Vermeidet "Leser/Leserin".
|}
 
'''Beispiel-Satz (Vorher/Nachher):'''
*'''❌ Vorher:''' "Der Administrator muss den Benutzer anlegen, damit der Benutzer sich anmelden kann."
*'''✅ Nachher:''' "Die '''Verwaltung''' muss den '''Nutzer''' anlegen, damit sich die '''Person''' anmelden kann."
*'''✅ Alternativ (Plural):''' "'''Die Verwaltung''' muss '''Nutzer''' anlegen, damit sich '''sie''' anmelden können."
 
----
 
== 3. 📑 Überschriften-Hierarchie ==
 
=== Konsistente Ebenen ===
<pre>
= Haupttitel (Seitentitel) =
== Hauptkapitel ==
=== Unterkapitel ===
==== Detail (nur bei Bedarf) ====
</pre>
 
'''Beispiel:'''
<pre>
= Klienten =
== Aufbau ==
== Verlaufsdokumentation ==
=== Beispiel von Einträgen ===
</pre>
 
'''Vermeiden:'''
* Überspringen von Ebenen (nicht von = direkt zu ===)
* Zu viele Ebenen (max. 4)
* "Inhaltsverzeichnis" als Überschrift (MediaWiki generiert das automatisch)
 
----
 
== 4. 💻 Code & Technische Begriffe ==
 
=== Formatierung nach Typ ===


{| class="wikitable"
{| class="wikitable"
Zeile 134: Zeile 23:
| '''Menüpunkte''' || <code>Backticks</code> || <code>Administration</code>, <code>Weiteres</code>
| '''Menüpunkte''' || <code>Backticks</code> || <code>Administration</code>, <code>Weiteres</code>
|-
|-
| '''Befehle/Commands''' || <code>Code-Block</code> || <code>gpupdate /force</code>
| '''Befehle''' || <code>Code-Block</code> || <code>gpupdate /force</code>
|-
|-
| '''Dateinamen''' || <code>Backticks</code> || <code>policies.json</code>
| '''Dateinamen''' || <code>Backticks</code> || <code>policies.json</code>
|-
|-
| '''URLs''' || Markdown-Link || <nowiki><https://example.com></nowiki>
| '''URLs''' || [[Markdown-Link]] || [Linktext](https://...)
|-
| '''IDs/Keys''' || <code>Code-Block</code> || <code>keacgmkcjipbdcpfoobecgkhfhffodhi</code>
|-
| '''Schlüsselwörter''' || '''Fett''' || '''Administrator''', '''Berechtigungen'''
|}
 
=== Code-Blöcke verwenden für: ===
* Shell-Befehle
* JSON-Inhalte
* Konfigurationswerte
* Pfadangaben
 
<syntaxhighlight lang="json">
{
  "installation_mode": "force_installed",
  "update_url": "https://clients2.google.com/service/update2/crx"
}
</syntaxhighlight>
 
----
 
== 5. 🖼️ Bilder & Screenshots ==
 
=== Platzierung ===
* '''Logo''' ganz oben (alle Seiten haben <code>[[File:logo.png]]</code>)
* '''Screenshots''' direkt nach der Beschreibung, die sie illustrieren
* '''Nicht''' am Ende der Seite sammeln
 
=== Bildbeschriftung ===
<pre>
[[File:xxx.png|thumb|Beschreibung]]
</pre>
 
'''Regel:''' Jede Bild-Referenz sollte im Text erwähnt werden, bevor das Bild erscheint.
 
=== Größe ===
* Standard: '''300px-500px''' Breite
* Größere Bilder nur bei komplexen Diagrammen
 
----
 
== 6. 🔗 Interne Verweise ==
 
=== Konsistente Verlinkung ===
<pre>
[[Seitentitel|Anzeigetext]]
</pre>
 
'''Beispiel:'''
<pre>
Wählen Sie das Hauptmodul [[Klienten]] über die [[Seitenaufbau|Navigation]] aus.
</pre>
 
=== Vermeidung von "Rot-Links" ===
Vor dem Veröffentlichen prüfen:
* Existiert die verlinkte Seite?
* Ist der Titel korrekt geschrieben?
 
'''Fehlende Seiten (aktuell):'''
* [[Berechtigungsblatt]]
* [[Cloud]]
* [[Benutzerkonto]]
 
----
 
== 7. 📋 Tabellen ==
 
=== Wann verwenden? ===
* Vergleich von Optionen
* Konfigurationswerte
* Schritt-für-Schritt-Anleitungen
 
=== Format ===
{| class="wikitable"
|-
|-
! Feld !! Wert !! Beschreibung
| '''IDs / Keys''' || <code>Code-Block</code> || <code>keacgmkcjipbdcpfoobecgkhfhffodhi</code>
|-
|-
| '''ID''' || <code>abc123</code> || Eindeutige Kennung
| '''Schlüsselwörter''' || '''Fett''' || '''Berechtigungen''', '''Konfiguration'''
|-
|-
| '''URL''' || <code>https://...</code> || Update-Server
| '''Code-Blöcke''' || Syntax-Highlighting || <syntaxhighlight lang="json">...</syntaxhighlight>
|}
|}


'''Tipp:''' Fettmarkierung in der ersten Spalte für bessere Lesbarkeit.
=== 4. Terminologie ===
 
Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen:
----
 
== 8. 🎨 Terminologie ==
 
=== Einheitliche Begriffe ===


{| class="wikitable"
{| class="wikitable"
Zeile 233: Zeile 43:
! Begriff !! Verwenden !! Nicht verwenden
! Begriff !! Verwenden !! Nicht verwenden
|-
|-
| '''Benutzer''' || '''Nutzer''' / '''Person''' || User, Account, Benutzer (technisch)
| Person || Nutzer / Person || User, Account, Benutzer (technisch)
|-
|-
| '''Klienten''' || Klienten || Kunden, Fälle
| Rolle || Klienten || Kunden, Fälle
|-
|-
| '''Eintrag''' || Eintrag || Datensatz, Record
| Daten || Eintrag || Datensatz, Record
|-
|-
| '''Modul''' || Modul || Feature, Komponente
| Baustein || Modul || Feature, Komponente
|-
|-
| '''Administration''' || Administration || Admin-Bereich, Settings
| Bereich || Administration || Admin-Bereich, Settings
|-
|-
| '''Mitarbeiter''' || '''Mitarbeitende''' || Mitarbeiter, Personal
| Personenkreis || Mitarbeitende || Mitarbeiter, Personal
|-
|-
| '''Toolbar''' || Toolbar || Werkzeugleiste
| Leiste || Toolbar || Werkzeugleiste
|-
|-
| '''Navigation''' || Navigation || Menü, Sidebar
| Bereich || Navigation || Menü, Sidebar
|}
|}


----
=== 5. 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. <code>Datei:Logo.png</code>).


== 9. ⚠️ Warnhinweise & Hinweise ==
=== 6. Interne Verweise ===
* '''Konsistenz:''' Verlinkungen müssen einheitlich aufgebaut sein.
* '''Prüfung:''' Vor dem Veröffentlichen sicherstellen, dass keine „Rot-Links" (fehlende Seiten) vorhanden sind.


=== Konsistente Boxen ===
=== 7. Tabellen ===
* '''Struktur:''' Spalten für Feld, Wert und Beschreibung.
* '''Lesbarkeit:''' Die erste Spalte (Feldname) wird '''fett''' markiert.
* '''Inhalt:''' Technische Werte (IDs, URLs) in <code>Backticks</code> setzen.


{| class="wikitable"
=== 8. Warnhinweise & Hinweise ===
|-
* Verwendung konsistenter Boxen-Styles für Warnungen, Tipps und wichtige Hinweise, um diese visuell hervorzuheben.
! Typ !! Format !! Beispiel
 
|-
=== 9. Aufbau eines Eintrags ===
| '''Wichtig''' || '''Fett''' || '''Wichtig:''' Dieses Plugin ist nur für Outlook Classic
Jeder Eintrag zu einer Funktion, einem Modul oder einem Prozess folgt diesem Standard-Aufbau, um die Auffindbarkeit und Verständlichkeit zu maximieren:
|-
 
| '''Hinweis''' || Normal || Hinweis: Die Tabelle wird nur bis gestern geführt
# '''Überschrift (H2/H3):''' Klare, handlungsorientierte Bezeichnung der Funktion (z. B. „Einen neuen Eintrag erstellen").
|-
# '''Kurzeinführung:''' 1–2 Sätze, die den Zweck der Funktion und den Nutzen für den Anwender erklären.
| '''Achtung''' || ''Kursiv'' || ''Achtung:'' Neue Version nicht kompatibel mit alter Software
# '''Voraussetzungen:''' Benötigte Berechtigungen (z. B. „Nur für den '''Administrator''' verfügbar") oder notwendige Vorbereitungsschritte.
|}
# '''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 ==


== 10. 📄 Checkliste vor Veröffentlichung ==
Mit dieser Funktion fügen Sie einen neuen Datensatz in die Datenbank hinzu.


Bevor eine Seite online geht:
'''Voraussetzungen:''' Sie benötigen die Berechtigung „Einträge bearbeiten".


* [ ] Anrede durchgehend "Sie"
# Klicken Sie im Menü auf <code>Neuer Eintrag</code>.
* [ ] '''Gendergerechte Sprache:''' "Nutzer" statt "Benutzer", "Mitarbeitende" statt "Mitarbeiter"?
# Geben Sie die erforderlichen Daten in die Felder ein.
* [ ] Überschriften-Hierarchie korrekt (= → == → ===)
# Bestätigen Sie mit <code>Speichern</code>.
* [ ] Alle Bilder haben Alt-Text
* [ ] Interne Links funktionieren (keine Rot-Links)
* [ ] Code/Commands in <code>Backticks</code> oder <code>Code-Blöcken</code>
* [ ] Keine Tippfehler in Menüpunkten
* [ ] Bilder sinnvoll platziert (nicht alle am Ende)
* [ ] Keine doppelten Inhalte mit anderen Seiten
* [ ] Logo nur einmal oben


----
'''Ergebnis:''' Der neue Eintrag erscheint in der Übersicht und ist für andere Nutzer sichtbar.


*Dieser Stil-Guide ist verbindlich für alle neuen und überarbeiteten Seiten der SocialOffice-Dokumentation.*
'''Siehe auch:''' [[Einträge bearbeiten]], [[Einträge löschen]]
</nowiki>

Version vom 4. Mai 2026, 15:28 Uhr

Stil-Guide für die SocialOffice-Dokumentation

Dieser Leitfaden sichert eine einheitliche, professionelle und inklusive Dokumentation.

1. 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.

2. 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.

3. Formatierung & Syntax

Konsistente Darstellung je nach Inhaltstyp:

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>

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. 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).

6. Interne Verweise

  • 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.
  • Lesbarkeit: Die erste Spalte (Feldname) wird fett markiert.
  • Inhalt: Technische Werte (IDs, URLs) in Backticks setzen.

8. Warnhinweise & Hinweise

  • Verwendung konsistenter Boxen-Styles für Warnungen, Tipps und wichtige Hinweise, um diese visuell hervorzuheben.

9. Aufbau eines Eintrags

Jeder Eintrag zu einer Funktion, einem Modul oder einem Prozess folgt diesem Standard-Aufbau, um die Auffindbarkeit und Verständlichkeit zu maximieren:

  1. Überschrift (H2/H3): Klare, handlungsorientierte Bezeichnung der Funktion (z. B. „Einen neuen Eintrag erstellen").
  2. Kurzeinführung: 1–2 Sätze, die den Zweck der Funktion und den Nutzen für den Anwender erklären.
  3. Voraussetzungen: Benötigte Berechtigungen (z. B. „Nur für den Administrator verfügbar") oder notwendige Vorbereitungsschritte.
  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 oder passiert.
  6. Siehe auch: Liste relevanter verwandter Themen als interne Links.

Beispielstruktur für einen Eintrag: == 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]]

Abgerufen von „https://doku.socialoffice.ch/index.php?title=Stil-Guide&oldid=488“