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.
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 werfen oder in einem Github-Issue fragen, um loszulegen.
Annahmen zur Leserschaft
Die Dokumentation geht davon aus, dass Benutzer ein grundlegendes Verständnis für die Verwendung von Webbrowsern und gängige Software-Design-Konzepte haben. Das bedeutet, dass Funktionen detailliert beschrieben werden, aber zum Beispiel nicht auf der Ebene, wie man ein Dropdown-Feld öffnet.
Der Zammad-Administrator sollte zudem über ein technisches Grundverständnis verfügen und auch die Arbeitsabläufe und Kommunikationsprozesse in seinem Unternehmen kennen.
Bei selbst gehosteten Instanzen sollten Systemadministratoren auch mit den Grundlagen der Linux-Systemverwaltung vertraut sein. Der Zugang zum Host-System (z.B. über SSH) und administrative Rechte werden für Systemadministratoren 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 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 die Relevanz berücksichtigt werden. Wenn Teile mit einem gebräuchlichen Anwendungsfall fehlen, sollte beabsichtigt werden, diese in die Dokumentation aufzunehmen.
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, 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 zur Erstellung der Website.
- Die Sprache der Quelldateien ist amerikanisches Englisch.
- Die Übersetzung der Dokumentation erfolgt über Weblate, siehe Abschnitt Übersetzung 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.
- Seitentitel und Überschriften: Großschreibung des ersten Buchstabens aller Wörter mit Ausnahme von Artikeln usw., siehe Title Case auf Wikipedia.
- 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.
- Verwenden Sie einen Detail-Kasten, wenn der Inhalt nicht für alle Leser relevant ist oder den Lesefluss unterbrechen könnte.
- Fügen Sie, wenn nötig, Screenshots ein. Die bevorzugte Art, Screenshots von Zammad hinzuzufügen, ist, sie automatisch mit Cypress 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 hier 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
odersh
. Wenn keine Sprache zutrifft, verwenden Sieplain
. - 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.
Beispiele
Text und UI
Typ | Hervorhebung in Dokumentation | Markdown Syntax |
---|---|---|
Buttons | Sign in | `Sign in` |
Felder und UI-Elemente | Name | **Name** |
Orte/Pfade | Einstellungen > Kanäle > Email | _Einstellungen > Kanäle > Email_ |
Tastaturkürzel | x | [[x]] |
Struktur der Überschrift
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 angepasster Text
Dieser Abschnittstitel verwendet ein Badge des Typs "warning". Es sind auch andere Badges verfügbar, siehe https://vitepress.dev/reference/default-theme-badge#usage.
Usage
Text/Titel, dem ein Badge hinzugefügt werden soll <Badge type="warning" text="freier Text" />
Spezial-Boxen
INFO
Dies ist eine Infobox.
Usage
::: info
Dies ist eine Infobox.
:::
TIP
Dies ist ein Tipp.
Usage
::: tip
Dies ist eine Tipp-Box.
:::
WARNING
Dies ist eine Warnung.
Usage
::: warning
Dies ist eine Warnungs-Box.
:::
DANGER
Dies ist eine gefährliche Warnung.
Usage
::: warning
Dies ist eine gefährliche Warnung.
:::
Details
Dies ist ein Detailblock.
Verwendung:
::: details Box title shown in collapsed state
Dies ist der Inhalt, der im ausgeklappten Zustand angezeigt wird.
:::
Definitionslisten
- Erster Begriff tag1
- Dies ist die Definition des ersten Begriffs.
- Zweiter Begriff tag1 tag1
- Dies ist eine Definition des zweiten Begriffs.
- Dies ist eine weitere Definition des zweiten Begriffs.
Usage
Erster Begriff <Badge type="info" text="tag1" />
: Dies ist die Definition des ersten Begriffs
mit einer weiteren Zeile.