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 globales Publikum hat, vermeiden wir Fachjargon, Slang oder Redewendungen. Diese können Nicht-Muttersprachler der englischen Sprache verwirren und den Übersetzungsprozess verkomplizieren.
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 → | ***navi1 → navi2*** | Einstellungen → Laufwerkseinstellungen |
| Tab-Beschriftung | Fett | tab_name | Name eines auszuwählenden Tabs |
| Kontrollkästchen-Beschriftung | Fett | checkbox_label | Beschriftung einer Kontrollkästchen-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-Kursiv | tooltip-text | Kurze Erklärung bei Hover-Effekt |
| Menüpunkt | Fett + Kursiv | Menü → Untermenü → Element | Navigation durch verschachtelte Menüstrukturen |
| CLI- und Systemoutput | Schreibmaschinenschrift (inline code) | `text` | Navigieren Sie zu http://tower.local |
| Fehlermeldung | Schreibmaschinenschrift (inline code) | `Fehler: Nachricht` | Exakte Fehlermeldungen oder Logs |
| Dokumenttitel | Überschrift 1 | # Überschrift | (erscheint als) <h1>Überschrift</h1> |
| Dokumentabschnitt | Überschrift 2 | ## Überschrift | (erscheint als) <h2>Überschrift</h2> |
| Dokument-Teilabschnitt | Überschrift 3 | ### Überschrift | (erscheint 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, die wichtigsten Punkte oder Schritte zu erfassen, zu erinnern und zu befolgen. Es gibt zwei Haupttypen, jeder mit klaren Anwendungsfällen:
-
Ungeordnete Listen (Aufzählungszeichen): Verwenden Sie diese, um verwandte Elemente zu gruppieren, ohne eine Reihenfolge zu implizieren. Beispiel: "Liste der häufigen Unraid OS-Tools."
-
Ordered lists (numbered): Use to show a required sequence or procedure. Example: "To start the array..."
- 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 unbekannte Akronyme oder Initialismen immer vollständig aus, wenn Sie zum ersten Mal verwendet werden, gefolgt von der Abkürzung in Klammern. Beispiel: Virtuelle Maschinenfestplatte (VMDK)
Verlinkung zu anderen Dokumenten oder Seiten
Strategisches Verlinken ermöglicht es den Lesern, verwandte Themen zu erkunden und ihr Verständnis zu vertiefen. 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:
Sie können auch unseren [Einstiegsguide](../unraid-os/getting-started/quick-start-guide.mdx) überprüfen.
- Verlinken Sie immer zur relevantesten und autoritativsten verfügbaren Ressource.
Hinzufügen von Glossartermen
Unraid-Dokumente verwenden ein zentrales Glossarsystem, um Konsistenz und Zugänglichkeit technischer Begriffe sicherzustellen. Glossareinträge werden in der Datei glossary.yaml im Stammverzeichnis aufbewahrt.
Um einen Begriff hinzuzufügen oder zu aktualisieren:
- Bearbeiten Sie
glossary.yamlmit der folgenden Vorlage:
GlossaryTerm:
term: Anzeigename
def: Vollständige Definitionstext.
link: <a href="https://example.com">Optionaler detaillierter Link</a>
-
Um die Tooltip-Funktionalität hinzuzufügen, verweisen Sie auf den Begriff in der Dokumentation mit der folgenden Syntax:
%%Begriff|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.