Mithelfen, die Dokumentationsartikel zu verbessern und zu erweitern

Fedora-Dokumentationsteam Version F36 and newer Last review: 2023-05-01

Dieses Dokument erklärt die Arbeit mit dem Veröffentlichungssystem, das für die Fedora-Dokumentationswebsite verwendet wird. Es zeigt Ihnen, wie Sie zur bestehenden Dokumentation beitragen, komplett neue Inhalte erstellen und diese in den englischen Originalen sowie in möglichen Übersetzungen veröffentlichen können.

Es gibt viele verschiedene Möglichkeiten, zur Fedora-Dokumentation beizutragen. Einige davon ermöglichen Beiträge auch ohne technisches Wissen über Web-Content-Management-Systeme und deren Speicherung und Verwaltung. Das Werkzeug übernimmt all diese Aufgaben für Sie. So können sich Autoren ganz auf ihr Thema konzentrieren.

Schauen Sie doch mal bei uns vorbei. Sollten Sie auf einer Dokumentationsseite einen Fehler oder eine Ungenauigkeit entdecken, nutzen Sie bitte eines der unten beschriebenen Werkzeuge für Beiträge, um die Seite zu verbessern. Bei Fragen wenden Sie sich bitte an das Dokumentationsteam.

Lokale Autorenwerkzeuge bieten erfahrenen Autoren eine leistungsstarke Arbeitsumgebung. Sie ermöglichen effizientes Arbeiten auch an großen, komplexen und miteinander verknüpften Textsammlungen. Diese Werkzeuge richten sich an erfahrene Autoren.

Wie es funktioniert

Die Fedora-Dokumentation nutzt Antora zum Erstellen und Verwalten der Website. Die Dokumentation ist weitgehend statisch und wird nur gelegentlich aktualisiert. Genau darauf ist Antora spezialisiert. Es sammelt statische Textdokumente und wandelt sie in eine vollständige Webseite um, inklusive Navigation, Links, Formatierung, Positionierung, Anpassung an verschiedene Ausgabegeräte usw. Weitere Informationen zum Antora-Veröffentlichungssystem finden Sie auf der Antora-Webseite und in der Antora-Dokumentation.

Als Autor konzentrieren Sie sich auf den Inhalt und schreiben einfach drauflos.

Das allgemeine Vorgehen

Das Vier-Augen-Prinzip gilt für die Fedora-Dokumentation. Jeder Beitrag wird von einem anderen Autor geprüft. Sobald Sie Ihren Text oder Ihre Textänderung fertiggestellt haben, erstellt das System einen „Pull Request“ oder „Merge Request“, um Ihren Text in die Dokumentation zu integrieren. Dies veranlasst andere Autoren, Board-Mitglieder oder Mitglieder, die für den betreffenden Teil der Dokumentation zuständig sind, eine Prüfung zu beginnen und entweder die Aufnahme zu initiieren oder eine Diskussion anzustoßen. Bitte rechnen Sie mit einer Bearbeitungszeit von zwei bis drei Tagen.

Etwas zum technischen Hintergrund

Fedora verwendet AsciiDoc, um Text einfach und effizient zu formatieren. Es orientiert sich eng an natürlichen Schreibstilen in alltäglichen Notizen und eignet sich daher ideal zum Strukturieren und Hervorheben von Texten. So können Sie jeden beliebigen Editor verwenden, darunter nahezu jedes Textverarbeitungsprogramm, das AsciiDoc-Texte bearbeiten und speichern kann. Mehr dazu weiter unten.

Das AsciiDoc-Textdokument wird in mehreren Git-Repositories gespeichert. Dieses System ist besonders bei Softwareentwicklern beliebt und eignet sich hervorragend zur Verwaltung von Textdokumenten. Git fördert und erleichtert die Anwendung des Vier-Augen-Prinzips durch einen Pull-Request-Arbeitsablauf (auch Merge-Request-Arbeitsablauf genannt). Sie müssen sich nur dann mit den Details dieses Arbeitsablaufs auseinandersetzen, wenn Sie eine lokale Arbeitsumgebung für professionelle und regelmäßige Beiträge einrichten möchten. Alle anderen Werkzeuge erledigen die notwendigen Schritte im Hintergrund.

Voraussetzungen

Die einzigen Voraussetzungen für die Mitarbeit an der Fedora-Dokumentation sind:

Die Werkzeuge

Schnellzugriff: Der „Edit“-Knopf

  • Kleinere Korrekturen können so direkt über die Web-Oberfläche von Git Forge an einer einzelnen Datei vorgenommen werden.

  • Dafür ist Schreibzugriff zum Upstream-Repository erforderlich.

  • Nutzen Sie es eher als Ausnahme (ohne Review-Prozess) und nicht als empfohlene Option.

Der leichte Weg: Die Web-IDE auf Git forge

  • Nehmen Sie Änderungen an mehreren Dateien direkt über die Web-Oberfläche von Git Forge vor.

  • Es ist nicht nötig, irgendetwas auf dem lokalen Computer zu installieren oder Git-Befehle im Terminal auszuführen.

  • Pull Requests für den Reviewprozess (Merge Requests in GitLab)

  • Sie benötigen keine besonderen Berechtigungen oder Schreibzugriff auf das Originalprojekt.

Flexible und fortschrittliche Methode: Eine lokale Schreibumgebung schaffen

  • Arbeiten Sie offline mit mehreren Dateien und Repositories in Ihrem eigenen Tempo mit einem Texteditor und einem Terminal Ihrer Wahl.

  • Sie können die Seiten lokal erstellen und rendern, um Ihre Änderungen mithilfe des Podman-Containers zu testen.

Typische Möglichkeiten, sich einzubringen

Man kann verschiedene typische Arten von Beiträgen zur Fedora-Dokumentation unterscheiden, für die die verfügbaren Werkzeuge auf unterschiedliche Weise geeignet sind.

Es gibt viele Möglichkeiten, auf unterschiedliche Weise einen Beitrag zu leisten. Zum Beispiel Tippfehler korrigieren, kurze Informationen oder einen Link hinzufügen, einen Artikel aktualisieren oder einen neuen Artikel schreiben.

Eine vorhandene Dokumentationsseite aktualisieren

Diese Aufgabe umfasst kleinere Änderungen. Dazu gehören beispielsweise die Korrektur von Tippfehlern, das Hinzufügen kurzer Informationen oder eines Links sowie Textkorrekturen. Diese Art von Änderung ist insbesondere dann erforderlich, wenn die Dokumentation für eine neue Softwareversion aktualisiert werden muss.

Der Knopf File Edit ist für diesen Zweck praktisch.

Eine bestehende Dokumentationsdomäne erweitern

Diese Aufgabe umfasst das Hinzufügen eines oder mehrerer neuer Kapitel oder Abschnitte mit mehreren Kapiteln. Beispielsweise das Hinzufügen einer weiteren Containerisierungstechnik zur Dokumentation der Containerisierung.

Die Web-IDE ist hierfür ein praktisches Werkzeug. Eine lokale Entwicklungsumgebung ist zwar auch nutzbar, kann aber zu viel Aufwand bedeuten, wenn man nur an einem einzigen Dokument mitarbeiten möchte.

Es wird dringend empfohlen, den Plan vor Beginn über einen der Kommunikationskanäle des Dokumentationsteams vorzustellen. Sie erhalten dort Anregungen und Tipps zum Inhalt, aber auch zur Bearbeitung, beispielsweise zur Dateistruktur und Namenskonventionen.

Einführung eines neuen Dokumentationsbereichs

Diese Aufgabe umfasst ein neues, umfangreiches Themengebiet, beispielsweise neue Software oder ein neues Verwaltungswerkzeug. Dazu gehören beispielsweise die Einbindung mehrerer Abschnitte und Kapitel sowie die Erstellung eines neuen, separaten Repositorys.

Für diesen Schreibtyp ist die Einrichtung einer lokalen Schreibumgebung nützlich und lohnenswert.

In jedem Fall ist ein vorheriges Gespräch mit dem Dokumentationsteam notwendig, und sei es nur, um die technischen Voraussetzungen zu schaffen.

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