Unraid-Dokumentationsstilguide
Unraid OS wird vom LimeTech-Team und der Unraid-Community geformt. Unsere Dokumentation zielt darauf ab, umfassend, genau und aktuell zu sein. Da unsere Benutzer aus unterschiedlichen Hintergründen weltweit kommen, bildet dieser Leitfaden die Grundlage für ein konsistentes und klares Schreiben in allen Unraid-Dokumenten.
Schreibkonventionen
Stil und Ton
Unser Ton sucht eine Balance zwischen freundlich und formell, mit dem Ziel, detaillierte und genaue Inhalte zu liefern, mit denen sich Nutzer identifizieren können.
- Verwenden Sie formelle, direkte Anweisungen, wenn die Aktion festgelegt ist und keinen Spielraum für Abweichungen lässt.
- Verwenden Sie einen gesprächigen, erläuternden Ton, wenn Sie Kontext oder Szenarien bereitstellen, um die Inhalte zugänglicher zu machen.
Als Beitragender sollten Sie den Kontext und das Publikum berücksichtigen, wenn Sie Ihren Ton wählen.
Da Unraid OS ein weltweites Publikum hat, vermeiden wir Jargon, Slang oder Redewendungen. Diese können nicht-muttersprachliche Englischsprecher verwirren und den Übersetzungsprozess komplizieren.
Zielgruppe: Schreiben für alle Bereiche
Unsere Leser reichen von Linux-Experten, die Systeminternes verstehen, bis zu Anfängern, die Unraid zum ersten Mal nutzen.
Schreiben Sie klar und inklusiv, damit sowohl Experten als auch Neulinge problemlos folgen können.
Die ABC-Methode: Genauigkeit, Kürze, Klarheit
Wir priorisieren:
- Genauigkeit: Stellen Sie sicher, dass der Inhalt korrekt und gründlich getestet ist.
- Kürze: Seien Sie prägnant, ohne notwendige Details zu opfern.
- Klarheit: Verwenden Sie einfache Sprache und strukturieren Sie Inhalte für ein leichtes Verständnis.
Syntax
Unraid-Dokumentationen verwenden Markdown-Formatierung in Kombination mit spezifischen Textstilen, um Benutzern zu helfen, schnell Interface-Elemente zu identifizieren und in der WebGUI zu navigieren.
| Elementtyp | Stilkonvention | Markdown-Syntax | Beispiel / Beschreibung |
|---|---|---|---|
| Option oder Schaltflächenname | Fett | **text** | Wählen Sie Fertig |
| Benutzerdefinierter Eingabewert | Kursiv | *text* | Geben Sie einen Wert von 50GB ein |
| Navigationspfad | Fett + Kursiv; verwenden Sie → | ***nav1 → nav2*** | Einstellungen → Festplatteneinstellungen |
| Reiterbeschriftung | Fett | Tabellenname | Name eines zu wählenden Reiters |
| Checkbox-Beschriftung | Fett | Kontrollkästchenbeschriftung | Beschriftung einer Checkbox-Option |
| Dropdown-Menü-Option | Kursiv | Dropdown-Option | Wählbare Option in einem Dropdown |
| Dialogtitel | Überschrift 3 | ### Dialogtitel | Titel für Pop-up-Dialoge oder modale Fenster |
| Tooltip-Text | Inline-Schriftkursiv | tooltip text | Kurze Erklärung bei Hover-Effekt |
| Menüpunkt | Fett + Kursiv | Menü → Untermenü → Element | Navigation durch verschachtelte Menüs |
| CLI- und Systemoutput | Schreibmaschinenschrift (inline code) | `text` | Navigieren Sie zu http://tower.local |
| Fehlermeldung | Schreibmaschinenschrift (inline code) | `Fehler: Nachricht` | Exakte Fehlerstrings oder Logs |
| Dokumenttitel | Überschrift 1 | # Überschrift | (wird gerendert als) <h1>Überschrift</h1> |
| Dokumentabschnitt | Überschrift 2 | ## Überschrift | (wird gerendert als) <h2>Überschrift</h2> |
| Dokument-Teilabschnitt | Überschrift 3 | ### Überschrift | (wird gerendert als) <h3>Überschrift</h3> |
Jede Überschrift der Ebene 2 (##) und kleiner erscheint in der Inhaltsverzeichnis-Seitenleiste der Seite zur einfachen Navigation.
Formatierung für Listen und Tabellen
Die effektive Nutzung von strukturierten Elementen wie Listen und Tabellen verbessert die Informationsklarheit, unterstützt das Verständnis und erleichtert den schnellen Zugriff.
Listen
Listen helfen Benutzern, Hauptpunkte oder Schritte aufzufassen, zu erinnern und zu befolgen. Es gibt zwei Haupttypen, die jeweils klare Anwendungsfälle haben:
-
Ungeordnete Listen (Punkte): Nutzen Sie sie, um verwandte Elemente ohne Reihenfolgenangabe zu gruppieren. Beispiel: "Liste der gängigen Unraid OS-Werkzeuge."
-
Geordnete Listen (nummeriert): Nutzen Sie sie, um eine erforderliche Reihenfolge oder Prozedur anzuzeigen. Beispiel: "Um das array zu starten..."
- Versuchen Sie, die Liste mit einem klaren Anfangssatz einzuführen, der in einem Doppelpunkt endet.
- Verwenden Sie maximal 4–6 Elemente in einer ungeordneten Liste, um das Scannen und Merken zu erleichtern. Längere Listen sind möglicherweise besser als Tabelle darzustellen.
Tabellen
Tabellen sind eine großartige Möglichkeit, zusammenhängende Daten durch Gruppierung in Zeilen und Spalten zu organisieren, wodurch Vergleiche schneller und präziser werden.
- Verwenden Sie Tabellen, wenn mehrere zusammenhängende Datenpunkte von einem Vergleich nebeneinander profitieren.
- Vermeiden Sie Tabellen mit nur 1 oder 2 Zellen; stattdessen verwenden Sie Aufzählungslisten oder Sätze.
- Fügen Sie der Tabelle einen einleitenden Satz hinzu, der deren Zweck und Inhalt erklärt.
Abkürzungen, Akronyme und Initialwörter
Um Verwirrung bei den Lesern zu verringern, befolgen Sie diese Prinzipien bezüglich Abkürzungen:
- Abkürzungen sind verkürzte Formen von Wörtern, die in den Unraid-Dokumentationen normalerweise überflüssig sind, es sei denn, sie sind allgemein anerkannt.
- Akronyme bilden neue Wörter aus den Anfangsbuchstaben anderer Wörter (z.B. RAID).
- Initialwörter verwenden Initialen, die einzeln ausgesprochen werden (z.B. OS, ZFS).
Empfehlungen:
- Bevorzugen Sie bestehende, bekannte Akronyme oder Initialwörter, die Ihrem Publikum vertraut sind.
- Vermeiden Sie die Erstellung neuer Abkürzungen nur um der Kürze halber.
- Schreiben Sie ungewohnte Akronyme oder Initialwörter beim ersten Gebrauch immer aus und fügen Sie die Abkürzung in Klammern hinzu. Beispiel: Virtuelle Maschinen-Disk (VMDK)
Verlinkung zu anderen Dokumenten oder Seiten
Strategisches Verlinken erlaubt es den Lesern, verwandte Themen zu erkunden und ihr Verständnis zu verbessern. Verwenden Sie diese Richtlinien für praktisches und zugängliches Hyperlinking.
Leitlinien für den Linktext
- Der Linktext sollte das Ziel klar beschreiben und allen Lesern den Zweck des Links verständlich machen.
- Meiden Sie vage Linktexte wie "Hier klicken" oder "Mehr lesen", da diese den Kontext vermissen lassen.
- Vermeiden Sie die Verwendung von rohen URLs als Inline-Linktext.
Formatieren von Links
- Verwenden Sie Inline-Markdown-Links:
You can also check our [getting started guide](../unraid-os/getting-started/quick-start-guide.mdx).
- Verlinken Sie immer zur relevantesten und autoritativsten verfügbaren Ressource.
Hinzufügen von Glossartermen
Unraid Dokumentationen verwenden ein zentrales Glossarsystem, um die Konsistenz und Zugänglichkeit technischer Begriffe sicherzustellen. Glossareinträge werden in der Datei glossary.yaml im Hauptverzeichnis aufbewahrt.
Um einen Begriff hinzuzufügen oder zu aktualisieren:
- Bearbeiten Sie
glossary.yamlmit der folgenden Vorlage:
GlossaryTerm:
term: Display Name
def: Full definition text.
link: <a href="https://example.com">Optional detailed link</a>
-
Um die Tooltip-Funktionalität hinzuzufügen, verweisen Sie auf den Begriff in der Dokumentation mit der folgenden Syntax:
%%Term|GlossaryTerm%%... wobei die linke Seite des Pipes der Text ist, den Sie anzeigen möchten, während die rechte Seite der entsprechende Eintrag im YAML-Glossar ist.
-
- Die Glossarseite wird automatisch aktualisiert, um neue Begriffe einzuschließen.