Zum Inhalt springen

Stil-Guide: Unterschied zwischen den Versionen

Aus SocialOffice Dokumentation
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
 
(4 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 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. Er folgt dem natürlichen Arbeitsfluss beim Erstellen von Einträgen.


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


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


== 1. 🎯 Anrede & Sprache ==
=== 4. Terminologie ===
 
Verwendung einheitlicher Begriffe zur Vermeidung von Missverständnissen.
=== Regel: Durchgehend "Sie"-Form ===
Die Dokumentation spricht den Nutzer höflich und professionell an.


{| class="wikitable"
{| class="wikitable"
|-
|-
! ✅ Richtig !! ❌ Falsch
! Begriff !! Verwenden !! Nicht verwenden !! Anmerkung
|-
|-
| "Wählen Sie das Modul aus" || "Wähle das Modul aus"
| Person (allgemein) || Nutzer / Person || User, Account || Im allgemeinen Text.
|-
|-
| "Sie können Dateien anhängen" || "Du kannst Dateien anhängen"
| Rolle (System) || Benutzer || User, Account || Fester Systembegriff.
|-
| "Ö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
| Rolle (Modul) || Mitarbeiter || Kunden, Fälle || Fester Modulname ("Hauptmodul Mitarbeiter").
|-
|-
| '''Der Benutzer''' || '''Der Nutzer''' / '''Die Person''' || "Der '''Nutzer''' kann..." statt "Der Benutzer kann..."
| Daten || Eintrag || Datensatz, Record ||  
|-
|-
| '''Der Administrator''' || '''Die Verwaltung''' / '''Die Admin-Person''' || "Die '''Verwaltung''' erstellt..."
| Baustein || Modul || Feature, Komponente ||  
|-
|-
| '''Der Kunde''' || '''Die Klientin / Der Klient''' || Im Modul "Klienten" ist "Klient" bereits neutral, aber "Die Person" ist oft besser.
| Bereich || Administration || Admin-Bereich, Settings ||
|-
|-
| '''Die Mitarbeiter''' || '''Das Team''' / '''Die Mitarbeitenden''' || "'''Die Mitarbeitenden''' können..."
| Leiste || Toolbar || Werkzeugleiste ||  
|-
|-
| '''Der Leser''' || '''Die Leserin / Der Leser''' (nur wenn nötig) || Besser: "'''Wer dies liest'''..."
| Bereich || Navigation || Menü, Sidebar ||  
|}
|}


=== B. Priorität 2: Geschlechtsneutrale Bezeichnungen ===
=== 5. Aufbau eines Eintrags ===
Wenn eine neutrale Umschreibung nicht möglich ist oder der Begriff fest etabliert ist (z. B. in Datenbankfeldern), verwenden Sie '''geschlechtsneutrale Formen'''.
Jeder Eintrag folgt diesem Standard-Aufbau, um die Auffindbarkeit und Verständlichkeit zu maximieren:


'''Empfohlene Form:''' '''Das Binnen-I''' oder '''Paarform''' (je nach Kontext).
# '''Überschrift (H2/H3):''' Klare, handlungsorientierte Bezeichnung (z. B. „Einen neuen Eintrag erstellen").
*Hinweis: Für technische Dokumentation (Software-UI) ist oft das '''Binnen-I''' oder die '''Pluralform''' am besten lesbar.*
# '''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.


{| class="wikitable"
'''Beispielstruktur:'''
|-
<nowiki>
! Situation !! Empfehlung !! Beispiel
== Einen neuen Eintrag erstellen ==
|-
| '''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:'''
Mit dieser Funktion fügen Sie einen neuen Datensatz hinzu.
* 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 ===
'''Voraussetzungen:''' Sie benötigen die Berechtigung „Einträge bearbeiten".


{| class="wikitable"
# Klicken Sie im Menü auf <code>Neuer Eintrag</code>.
|-
# Geben Sie die Daten in die Felder ein.
! Begriff im System !! Empfehlung in der Doku !! Begründung
# Bestätigen Sie mit <code>Speichern</code>.
|-
| '''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 ==
'''Ergebnis:''' Der Eintrag erscheint in der Übersicht.


=== Konsistente Ebenen ===
'''Fehler & Troubleshooting:'''
<pre>
* ''Fehlermeldung "Speichern fehlgeschlagen":'' Prüfen Sie, ob alle Pflichtfelder ausgefüllt sind.
= Haupttitel (Seitentitel) =
== Hauptkapitel ==
=== Unterkapitel ===
==== Detail (nur bei Bedarf) ====
</pre>


'''Beispiel:'''
'''Siehe auch:''' [[Einträge bearbeiten]], [[Einträge löschen]]
<pre>
</nowiki>
= Klienten =
== Aufbau ==
== Verlaufsdokumentation ==
=== Beispiel von Einträgen ===
</pre>


'''Vermeiden:'''
=== 6. Formatierung & Syntax ===
* Überspringen von Ebenen (nicht von = direkt zu ===)
Konsistente Darstellung je nach Inhaltstyp während des Schreibens:
* 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 93:
| '''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
|-
|-
| '''ID''' || <code>abc123</code> || Eindeutige Kennung
| '''IDs / Keys''' || <code>Code-Block</code> || <code>keacgmkcjipbdcpfoobecgkhfhffodhi</code>
|-
|-
| '''URL''' || <code>https://...</code> || Update-Server
| '''Schlüsselwörter''' || '''Fett''' || '''Berechtigungen''', '''Konfiguration'''
|}
 
'''Tipp:''' Fettmarkierung in der ersten Spalte für bessere Lesbarkeit.
 
----
 
== 8. 🎨 Terminologie ==
 
=== Einheitliche Begriffe ===
 
{| class="wikitable"
|-
|-
! Begriff !! Verwenden !! Nicht verwenden
| '''Code-Blöcke''' || Syntax-Highlighting || <syntaxhighlight lang="json">...</syntaxhighlight>
|-
| '''Benutzer''' || '''Nutzer''' / '''Person''' || User, Account, Benutzer (technisch)
|-
| '''Klienten''' || Klienten || Kunden, Fälle
|-
| '''Eintrag''' || Eintrag || Datensatz, Record
|-
| '''Modul''' || Modul || Feature, Komponente
|-
| '''Administration''' || Administration || Admin-Bereich, Settings
|-
| '''Mitarbeiter''' || '''Mitarbeitende''' || Mitarbeiter, Personal
|-
| '''Toolbar''' || Toolbar || Werkzeugleiste
|-
| '''Navigation''' || Navigation || Menü, Sidebar
|}
|}


----
=== 7. Bilder & Screenshots ===
 
* '''Platzierung:''' Das Bild folgt erst, nachdem es im Fließtext erwähnt wurde.
== 9. ⚠️ Warnhinweise & Hinweise ==
* '''Beschriftung:''' Jedes Bild benötigt eine klare, beschreibende Bildunterschrift.
 
* '''Dateiname:''' Konsistente Benennung (z. B. <code>Datei:Logo.png</code>).
=== Konsistente Boxen ===
* '''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.
{| class="wikitable"
|-
! Typ !! Format !! Beispiel
|-
| '''Wichtig''' || '''Fett''' || '''Wichtig:''' Dieses Plugin ist nur für Outlook Classic
|-
| '''Hinweis''' || Normal || Hinweis: Die Tabelle wird nur bis gestern geführt
|-
| '''Achtung''' || ''Kursiv'' || ''Achtung:'' Neue Version nicht kompatibel mit alter Software
|}
 
----
 
== 10. 📄 Checkliste vor Veröffentlichung ==


Bevor eine Seite online geht:
=== 8. 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.


* [ ] Anrede durchgehend "Sie"
=== 9. Warnhinweise & Hinweise ===
* [ ] '''Gendergerechte Sprache:''' "Nutzer" statt "Benutzer", "Mitarbeitende" statt "Mitarbeiter"?
* Verwendung konsistenter Boxen-Styles für Warnungen, Tipps und wichtige Hinweise, um diese visuell hervorzuheben.
* [ ] Überschriften-Hierarchie korrekt (= → == → ===)
* [ ] 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


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


*Dieser Stil-Guide ist verbindlich für alle neuen und überarbeiteten Seiten der SocialOffice-Dokumentation.*
=== 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.

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“