--- url: https://next.zammad.org/de/contribute/style-guide.md --- # Leitfaden für Stil und Inhalt Dieser Leitfaden bietet eine Übersicht über den Inhalt, der in der Zammad-Dokumentation enthalten sein sollte, sowie Formatierungs- und Stilrichtlinien, um Klarheit und Lesbarkeit zu gewährleisten. In den ersten Abschnitten geht es um allgemeine Informationen und Regeln. Am Ende folgt ein [Abschnitt mit Beispielen](#beispiele). Wenn Sie Fragen haben, können Sie diese in unserer Community stellen. Wenn Sie beitragen wollen, sollten Sie einen Blick auf unsere [Seite für Beiträge](contribute) werfen oder in einem [Github-Issue](https://github.com/zammad/zammad-org/issues){target=\_blank} fragen, um loszulegen. ## Annahmen zur Leserschaft In der Dokumentation wird davon ausgegangen, dass **Benutzer** ein grundlegendes Verständnis für die Verwendung von Webbrowsern haben und mit gängigen Konzepten der Softwaregestaltung vertraut sind. Das bedeutet, dass Funktionen detailliert beschrieben werden, aber zum Beispiel nicht auf dem Level wie man ein Dropdown-Menü öffnet. Der **Zammad-Administrator** sollte außerdem über ein technisches Grundverständnis verfügen und mit den Arbeitsabläufen und Kommunikationsprozessen innerhalb seiner Firma vertraut sein. Bei selbst gehosteten Instanzen sollten **Systemadministratoren** auch mit den Grundlagen der Linux-Systemverwaltung vertraut sein. Der Zugriff auf das Host-System (z.B. über SSH) und administrative Rechte werden als gegeben vorausgesetzt. ## Inhalt Die Dokumentation soll Informationen zu folgenden Themen enthalten: * Wie man Zammad benutzt * Wie man Zammad als Administrator verwaltet (z.B. nach der Installation einrichten, Einstellungen anpassen, Funktionen konfigurieren) * Verschiedene Möglichkeiten, Zammad zu installieren * Zusätzliche Anleitungen, wenn eine (Host-)Systemkonfiguration und/oder eine Konfiguration von Drittsystemen erforderlich ist. Was die **Detailtiefe** betrifft, so sollten die [Annahmen zur Leserschaft](#annahmen-zur-leserschaft) berücksichtigt werden. Da eines der Ziele von Zammad darin besteht, intuitiv und benutzerfreundlich zu sein, ist es nicht notwendig, jeden Klick im Detail zu beschreiben. Wichtige Schritte sollten jedoch enthalten sein. Die Leser sollen so schnell und einfach wie möglich ihr Ziel erreichen, ohne viel lesen zu müssen. Da eine Dokumentation nicht alles abdecken kann (sonst wäre sie auf einer codeähnlichen Detailebene), muss auch die Relevanz berücksichtigt werden. Wenn Bereiche mit einem gängigen Anwendungsfall fehlen, sollte beabsichtigt werden, diese zu ergänzen. ## Stil und Regeln Die nächsten Abschnitte behandeln allgemeine Dinge, die beim Schreiben der Dokumentation zu beachten sind. Danach finden Sie einen Abschnitt mit einigen [Beispielen](#beispiele), wie Sie den Inhalt formatieren und strukturieren können. ### Grundlagen * Die Dokumentation ist in der Auszeichnungssprache Markdown geschrieben. Die Quelldateien haben die Erweiterung `.md`. * Das System verwendet [VitePress](https://vitepress.dev/){target=\_blank} zur Erstellung der Website. * Die Sprache der Quelldateien ist amerikanisches Englisch. * Die Übersetzung der Dokumentation erfolgt über Weblate, siehe Abschnitt [Übersetzung](contribute#ubersetzung) auf der "Beitragen"-Seite für weitere Details. ### Stil * Verwenden Sie kurze und klare Sätze und fokussieren Sie sich auf Informationen statt auf Komplexität. * Verwenden Sie bei Seitentiteln und Überschriften die "Sentence case"-Schreibweise. Schreiben Sie das erste Wort sowie den ersten Buchstaben aller Eigennamen (z.B. Zammad, Elasticsearch, Docker, GitLab) und Abkürzungen (SLA, SSO, API, JSON usw.) groß. * Verwenden Sie eine Breadcrumb-Trennung für Pfade und Orte mit `>` als Trennzeichen und formatieren Sie den Pfad kursiv, z.B. *Einstellungen > Kanäle > Chat*. * Verwenden Sie die Codehervorhebung für Code-Snippets und Befehle. * Verwenden Sie bei Bedarf [Info-, Tip-, Warning- und Danger-Boxen](#spezial-boxen). * Verwenden Sie einen [Detail-Kasten](#custom-boxes), wenn der Inhalt nicht für alle Leser relevant ist oder den Lesefluss unterbrechen könnte. * Falls vorhanden, verwenden Sie Icons für wichtige UI-Buttons wie ::+:: und ::x:: (siehe [Beispiele](#text-and-ui) unten). * Verwenden Sie eine Auszeichnung wie \[\[ctrl]] und \[\[x]], um einen Tastendruck darzustellen (siehe [Beispiele](#text-und-ui) unten). * Fügen Sie, wenn nötig, Screenshots ein. Die bevorzugte Art, Screenshots von Zammad hinzuzufügen, ist, sie automatisch [mit Cypress](https://github.com/zammad/zammad-org?tab=readme-ov-file#automatic-screenshots-cypress){target=\_blank} zu erstellen. Dies unterstützt die Pflege der Dokumentation, da die Screenshots bei jedem Durchlauf der Build-Pipeline neu generiert werden. Bitte beachten Sie, dass die Verwendung von Cypress nicht Teil dieser Dokumentation ist. * Geben Sie Schritt-für-Schritt-Anleitungen mit klaren Erklärungen. * Verwenden Sie Beispiele oder Szenarien, um Konzepte zu veranschaulichen. * Fügen Sie bei Bedarf relevante Bilder oder Diagramme ein. * Schreiben Sie Abkürzungen bei der ersten Verwendung vollständig aus oder nehmen Sie sie in das Glossar auf und verweisen Sie darauf. Weit verbreitete und gängige Abkürzungen können von dieser Regel ausgenommen werden. * Im Zweifelsfall können Sie sich an der vorhandenen Dokumentation orientieren. ### Konventionen Der Dokumentations-Stack enthält automatische Prüfungen (Linting), um die Einhaltung des Styleguides und der allgemeinen Regeln für Markdown-Dateien sicherzustellen. Um zu prüfen, ob Ihre Änderungen konform sind, führen Sie `pnpm lint` aus, um die Prüfung durchzuführen. Einige der erkannten Probleme können sogar automatisch behoben werden, indem `pnpm lint:fix` ausgeführt wird. Stellen Sie sicher, dass Sie die Prüfung durchführen, bevor Sie Ihre Änderungen commiten. Andernfalls wird die Erstellung der Dokumentation fehlschlagen. Das verwendete Linting hat einige eingebaute Regeln, die Sie im [offiziellen Repository](https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#rules--aliases){target=\_blank} finden können. Einige wichtige und von uns angepasste Regeln sind unten aufgeführt. * Die Zeilenlänge von 120 Zeichen in der Quelldatei darf bei Standardtext nicht überschritten werden. Achten Sie darauf, dass Sie einen Zeilenumbruch verwenden, bevor Sie diese Grenze erreichen. Ein visueller Indikator in Ihrem Editor kann hilfreich sein. Dies gilt nicht für spezielle Inhalte wie Pfade zu Screenshots und lange Links. * Mehrere aufeinanderfolgende Leerzeilen sind nicht zulässig. * Leerzeilen vor und nach Überschriften und Codeblöcken sind erforderlich. * Verwenden Sie ` ``` ` (Backticks) für abgegrenzte Codeblöcke, gefolgt von einem obligatorischen Sprach-Tag, z.B. `ruby` oder `sh`. Wenn keine Sprache zutrifft, verwenden Sie `plain`. * Verwenden Sie `-` für Aufzählungen (ungeordnete Liste) wie diese. * Um leicht zwischen **fett** und *kursiv* zu unterscheiden, verwenden Sie `_` um den Text in kursiv und `**` in fett zu setzen (z.B. `_kursiv_` vs. `**fett**`). * Mehrere Überschriften mit gleichem Inhalt sind nicht zulässig. * Jedes Dokument muss genau eine `h1`-Überschrift als Titel haben. * Die Auflösung von manuellen Screenshots der ganzen Seite für die *Mobilansicht* beträgt 400x867 Pixel. * Die Auflösung von manuellen Screenshots der ganzen Seite für die *Desktop-View* beträgt 1920x1080 Pixel. Zusätzlich zu `pnpm lint` nutzt das Repository [Vale](https://vale.sh/){target=\_blank} für die Überprüfung von Textinhalten. Vale überprüft die einheitliche Groß- und Kleinschreibung von Markennamen (z.B. GitHub, GitLab, Elasticsearch), kennzeichnet nicht empfohlene Begriffe und setzt die Regeln der Wortliste durch. Es wird automatisch beim Commit ausgeführt und in der CI zusammen mit dem Markdownlint-Job. Um es manuell auszuführen, verwenden Sie `pnpm vale`. ### Beispiele #### Text und UI | Typ | Hervorhebung in Dokumentation | Markdown Syntax | |-------------------------------------------------|-----------------------------------|-------------------------------------| | Schaltflächen | `Aktualisieren` | `` `Aktualisieren` `` | | Fields, labeled UI elements, menu items | **Name** | `**Name**` | | Pfade / Navigations-Schritte | *Einstellungen > Kanäle > Email* | `_Einstellungen > Kanäle > Email_` | | Dateien und Verzeichnispfade | `/opt/zammad` | `` `/opt/zammad` `` | | Platzhalter in Konfiguration | `` | `` `` `` | | Platzhalter für API-Anfragen | `{ticket id}` | `` `{ticket id}` `` | | Konfigurationswerte Kommandozeile, Ports, Keys | `9200` | `` `9200` `` | | Tastaturkürzel | \[\[x]] | `[[x]]` | | Hinzufügen Schaltfläche | ::+:: | `::+::` | | Löschen Schaltfläche | ::x:: | `::x::` | | Aktions-Schaltfläche | ::a:: | `::a::` | | Schaltfläche kopieren in Zwischenablage | ::c:: | `::c::` | #### Gliederung mit Überschriften Jede Dokumentationsdatei muss genau einen Titel auf der obersten Ebene enthalten (z.B. `# Titel`). Die darunter liegenden Ebenen sollten immer mindestens zwei Abschnitte enthalten. Wenn nur ein Abschnitt vorhanden ist, sollte er mit dem übergeordneten Inhalt zusammengelegt werden. Beispiel: `# Titel der Seite` `## Abschnitt 1` `### Abschnitt 1.1` `### Abschnitt 1.2` `## Abschnitt 2` #### Überschrift mit Badge Dieser Abschnittstitel verwendet ein Badge des Typs "warning". Es sind auch andere Badges verfügbar, siehe . **Verwendung:** ::: details ```md Text/Titel, dem ein Badge hinzugefügt werden soll ``` ::: #### Spezial-Boxen ::::: info Dies ist eine Infobox. **Verwendung:** :::: details ```md ::: info Dies ist eine Infobox. ::: ``` :::: ::::: ::::: tip Dies ist ein Tipp. **Verwendung:** :::: details ```md ::: tip Dies ist eine Tipp-Box. ::: ``` :::: ::::: ::::: warning Dies ist eine Warnung. **Verwendung:** :::: details ```md ::: warning Dies ist eine Warnungs-Box. ::: ``` :::: ::::: ::::: danger Dies ist eine gefährliche Warnung. **Verwendung:** :::: details ```md ::: warning Dies ist eine gefährliche Warnung. ::: ``` :::: ::::: :::: details Dies ist eine Detail-Box. **Verwendung:** ```md ::: details Dies ist der Inhalt, der im ausgeklappten Zustand angezeigt wird. ::: ``` :::: #### Definitionslisten Erster Begriff : Dies ist die Definition des ersten Begriffs. Zweiter Begriff : Dies ist eine Definition des zweiten Begriffs. : Dies ist eine weitere Definition des zweiten Begriffs. **Verwendung:** ::: details ```md Erster Begriff : Dies ist die Definition des ersten Begriffs mit einer weiteren Zeile. ``` ::: #### Hervorhebung mit Boxen Um verschiedene Optionen oder Varianten hervorzuheben, können anklickbare Kästen verwendet werden. Die Definition des Inhalts erfolgt in Frontmatter, siehe folgendes Beispiel (Beispiel von oben): ```yml features: - icon: 🛠️ title: Simple and minimal, always details: Lorem ipsum... link: https://zammad.com linkText: This is a link target: _blank - icon: src: /assets/logo.svg title: Another cool feature details: Lorem ipsum... link: https://zammad.com - icon: dark: /assets/logo-flat-dark.svg light: /assets/logo-flat-light.svg title: Another cool feature details: Lorem ipsum... link: https://zammad.com ``` Um sie innerhalb des Inhaltsbereichs zu platzieren, fügen Sie einfach den Verweis `` an der Stelle ein, an der sie dargestellt werden sollen. #### Theme-abhängige Bilder Um bestimmte Bilder auf ein einzelnes Theme anzuwenden, können Sie dem entsprechenden Bild die CSS-Klasse `.dark-only` oder `.light-only` zuweisen: ```md ![Bild nur für dunkles Theme](/assets/logo-flat-dark.svg){.dark-only} ![Bild nur für helles Theme](/assets/logo-flat-light.svg){.light-only} ``` ![Bild nur für dunkles Theme](/assets/logo-flat-dark.svg){.dark-only width=240} ![Bild nur für helles Theme](/assets/logo-flat-light.svg){.light-only width=240}