Fedora-Dokumentationsstilrichtlinien

Fedora-Dokumentationsteam <https://discussion.fedoraproject.org/tag/docs-team> 21. April 2023
Dieser Leitfaden enthält Stilrichtlinien und Empfehlungen zur bevorzugten Terminologie für die Fedora Linux-Dokumentation. Das Dokumentationsteam hat diesen Leitfaden erstellt, um Korrektheit und Konsistenz in der Dokumentation zu gewährleisten.

Richtlinien für den Schreibstil

Schreiben Sie klar und verwenden Sie kürzere Sätze

Je länger eine Benutzerdokumentation ist, desto schwieriger ist sie zu verstehen. Kurz und prägnant zu schreiben ist gut. Klarheit ist besser.

Vermeiden Sie Passivkonstruktionen

Das Passiv ist die Verwendung des Objekts eines Satzes als Subjekt. Zum Beispiel

  • Aktiv: The troops defeated the enemy.

  • Passiv: The enemy was defeated by the troops.

Vorsicht vor Gerundien (-ing)

Sie deuten auf Passiv hin. Formulieren Sie Ihren Satz so um, dass er aussagekräftig klingt. Zum Beispiel:

  • Schwach, passiv: Setting the foobar configuration option will make the application listen on all interfaces.

  • Stark, aktiv: Set the foobar configuration option to make the application listen on all interfaces.

Vermeiden Sie unnötige Zukunftsformen

Sofern Sie nicht tatsächlich über zukünftige Pläne oder Veröffentlichungen sprechen, ist die Gegenwartsform am besten geeignet.

  • Unnötige Zukunftsform: When you select Run, your program will start.

  • Gegenwartsform: When you select Run, your program starts.

Vermeiden Sie einen übermäßigen Gebrauch des Verbs „to be“ in Sätzen

Zu häufiges Verwenden von „is“ schwächt Ihre Sätze. Versuchen Sie, die Verbform der Wörter zu verwenden, die Sie an anderer Stelle im Satz weggelassen haben. Oft können Sie Wörter einfach weglassen oder die Imperativform (Befehls- oder Ratform) verwenden.

  • Schwach: Zambone is an app used for managing your private documents on a server.

  • Stark: Zambone manages your private documents on a server. Oder: Use Zambone to manage your private documents on a server.

  • Schwach: When setting up a file server, it is important to plan the directory structure carefully.

  • Stark: Plan the directory structure of the file server carefully before you set it up.

Verwenden Sie für Rechtschreibung und andere internationale Unterschiede die Standard-US-amerikanische Schreibweise

US-Englisch ist die Lingua franca des gesamten Fedora-Projekts.

Sorgen Sie für einen reibungslosen Übergang von allgemeinen Informationen zu spezifischen Anweisungen

Strukturieren Sie Ihren Artikel mit einer Zusammenfassung, Stichpunkten und den wichtigsten AsciiDoc-Auszeichnungen.

Vermeiden Sie lange Texte

Ausführliche Texte sind schwer lesbar. Strukturieren Sie Ihren Text stattdessen mit Absätzen, Stichpunkten und nummerierten Schritten. So kann der Leser den Text schnell erfassen und er wirkt vor allem nicht abschreckend. Fügen Sie am Anfang längerer Absätze eine kurze Zusammenfassung ein: Insbesondere nach Überschriften zweiter und dritter Ordnung („h2“ und „h3“, „=“ und „==“ in AsciiDoc) sollte ein kurzer Satz oder Absatz folgen, der das Ziel und/oder Thema der folgenden Absätze kurz beschreibt, die Aufmerksamkeit des Lesers auf die Kernaussage lenkt und seine Erwartungen weckt.

Typografischer Stil

Verwenden Sie Großbuchstaben für den Titel (h1) und einfach nur für den Titel.

Bitte nur den Artikeltitel großschreiben.

  • Falsch: Fedora documentation style guide

  • Richtig: Fedora Documentation Style Guide

Verwenden Sie für den Beitragstitel und die Überschriften die normale Groß- und Kleinschreibung.

Schreiben Sie Wörter im Titel Ihres Artikels oder in Überschriften nicht groß, außer Eigennamen.

  • Falsch: Technical Notes and Processes

  • Richtig: Technical notes and processes

Weniger ist mehr

Verwenden Sie Fettdruck nur für besonders wichtige Formulierungen oder Aussagen.

Verwenden Sie Kursivschrift für Systemobjekte, die in einem Satz erwähnt werden.

GUI- oder CLI-Elemente wie Knopfbeschriftungen, Menüeinträge oder Eingabeaufforderungen, die der Leser auf dem Bildschirm findet, Befehle oder Paketnamen

Verwenden Sie den vorformatierten Quelltext für die Befehlszeileneingabe oder -ausgabe

Verwenden Sie eine Shell-Eingabeaufforderung ($ oder #), um die Berechtigungsstufe anzugeben und die Eingabe von der Ausgabe zu trennen.

[source,console] ---- $ Befehl Arg1 Arg2 Ausgabezeile1 Ausgabezeile2 ----
Verwendung von Ermahnungen

Tipps, Hinweise und Warnungen stören, wenn sie übermäßig verwendet werden, den Lese- und Schreibfluss. Ermahnungen sollten nur dann ausgesprochen werden, wenn sie unbedingt notwendig sind.

Inhaltstipps

Diese Tipps betreffen Dinge, die Sie beim Anleiten von Nutzern beachten sollten – und was Sie vermeiden sollten. Bedenken Sie, dass Tausende von Lesern der Fedora-Dokumentation vertrauen, um Anweisungen zur Ausführung von Aufgaben zu erhalten. Seien Sie verantwortungsbewusst und hilfsbereit, testen Sie Ihre Beispiele sorgfältig, empfehlen Sie bewährte Vorgehensweisen und respektieren Sie die Sicherheit und die Entscheidungen der Nutzer.

Testen Sie Ihren Prozess

Verwenden Sie nach Möglichkeit eine frisch eingerichtete virtuelle Gastmaschine – oder zumindest ein neues Benutzerkonto. Führen Sie den Prozess von Anfang bis Ende durch, um sicherzustellen, dass er funktioniert. Beheben Sie Fehler, testen Sie den Vorgang und wiederholen Sie ihn gegebenenfalls!

Nutzen Sie freie und Open-Source-Software sowie offiziell paketierte Software

Der Artikel könnte sich mit nicht-freier Software befassen, die unter Fedora verwendet werden soll, wenn es für Fedora-Benutzer keine alternative freie Software gibt.

Verwenden Sie Distributionen der Fedora-Familie

Sofern Ihr Dokumentationsartikel nicht ausdrücklich auf einen distributionsübergreifenden Mechanismus abzielt, verwenden Sie Installationen, Container oder Distributionen innerhalb unserer Familie (Fedora, CentOS, RHEL).

Copr-Software muss mit einem Warnhinweis versehen sein

Das Copr-Buildsystem wird nicht vom Fedora-Releaseteam verwaltet und stellt keine offiziellen Software-Builds bereit. Wenn Sie Software von Copr verwenden, stellen Sie sicher, dass kein offizieller Build verfügbar ist. Falls doch, fügen Sie einen Hinweis wie diesen hinzu: „Copr is not officially supported by Fedora infrastructure. Use packages at your own risk“.

Vermeiden Sie ausgrenzende Sprache

Dies sind Beispiele für Formulierungen, die in Artikeln vermieden werden sollten:

  • blacklist/whitelist — Verwenden Sie stattdessen allowlist/denylist, da dies den Zweck direkter beschreibt.

  • master/slave — Verwenden Sie primary/secondary, primary/replica, active/passive, active/standby, oder ein ähnliches Konstrukt.

Verwenden Sie den korrekten Stil für Drittanbieter

Firmennamen, Projektnamen und Technologiebezeichnungen folgen nicht immer den üblichen englischen Stilregeln. Orientieren Sie sich im Zweifelsfall an der Formatierung seriöser Webseiten. Bei uneinheitlicher Formatierung durch seriöse Quellen entscheiden Sie nach bestem Wissen und Gewissen. Eine unvollständige Liste:

  • Copr anstelle von COPR

  • NVIDIA anstelle von Nvidia oder nVidia

  • Perl anstelle von PERL

  • Red Hat anstelle von Redhat oder RedHat

  • ThinkPad anstelle von Thinkpad

Abbildungen und Bildschirmfotos

Verwenden Sie ein frisches, standardmäßiges Fedora-System

Verwenden Sie nicht Ihr persönliches System oder Ihre bestehende Konfiguration. Es empfiehlt sich, eine virtuelle Maschine mit einer frischen Fedora-Varianteninstallation zu erstellen und die Schritte dort auszuführen.

Stellen Sie die Bildschirmauflösung auf einen angemessenen, aber nicht zu hohen Wert ein

Spezielle Bildschirmaufnahmesoftware für Desktop-Umgebungen erzeugt Bilder in der richtigen Größe für die Artikel. Wenn Sie ein Browserfenster aufnehmen, verwenden Sie die Option „Aktives Fenster“ in der Bildschirmaufnahmesoftware. Aktivieren Sie die Option, die Titelleiste des Fensters auszublenden.

Wenn Sie nur eine Anwendung, ein Pop-up oder bestimmte Bereiche anzeigen, verwenden Sie eine Option in der Software, um diese automatisch zuzuschneiden

Wenn die Aufnahme ein ganzes Browserfenster, die App in voller Größe oder den gesamten Bildschirm benötigt, wählen Sie ein mittelgroßes Vorschaubild. Verwenden Sie Bildbeschreibungen vor dem „block image“-Makro, um zu erläutern, welche Aktionen das Bild darstellt. Informationen zur ASCIIDoc-Auszeichnung finden Sie auf der nächsten Seite.

Verwendung von Verzeichnis- und Dateibenennungskonventionen

Um die Namenskonventionen einheitlich einzuhalten, sollte der ursprüngliche Titel des Artikels beibehalten, im Namen eines Unterverzeichnisses verwendet und der Titel der Bilder ergänzt werden.

Der Verzeichnispfad für Bilder in Fedora-Repositories lautet ~/modules/ROOT/assets/images/<ARTICLENAME_SHORTEND>/.png

Beispiel 1. Benennung von Unterverzeichnissen und Dateien
Lautet der Titel der H1-Überschrift „Finding and installing Linux applications“, so heißt die Datei finding-installing-linux-apps.adoc. Erstellen Sie in Ihrem geklonten lokalen Repository ein Unterverzeichnis und legen Sie die Bilder in den folgenden Pfaden ab: ~/modules/ROOT/assets/images/finding-installing-linux-apps/.png

Verarbeitungstipps

Überprüfen Sie Rechtschreibung und Grammatik

Überprüfen Sie Ihre Arbeit, bevor Sie einen Pull Request erstellen.

Schauen Sie in den Red Hat style guide

Verwenden Sie Vale, um Ihre Arbeit zu überprüfen und sicherzustellen, dass sie dem Red Hat Style Guide entspricht.

Want to help? Learn how to contribute to Fedora Docs ›