Richtlinien Dokumentation

Diese Seite beschreibt die Regeln beim Schreiben, Prüfen und dem Übersetzen von Dokumentationsinhalten der Godot Engine. Sehen Sie auch in die README des godot-docs GitHub-Repository und auf der Dokumentationshauptseite nach, wie Sie Kontakt mit dem Dokumentationsteam aufnehmen.

Wie man dazu beiträgt

Das Anlegen oder Bearbeiten von Dokumentationsseiten geschieht hauptsächlich über das godot-docs GitHub repository. Die Dokumentation in den Formaten HTML, PDF und EPUB wird aus den .rst-Dateien (reStructuredText Markup Language) in diesem Repository generiert. Werden diese Seiten über einen Pull Request aktualisiert und erfolgt ein Merge der Änderungen, so löst dies einen Neuaufbau der Onlinedokumentation aus.

Siehe auch

Für Erläuterungen zum Umgang mit Git und dem Arbeitsablauf beim Pull Request, sehen Sie sich die Ablauf eines Pull Request-Seite an. Die meisten der dort beschriebenen Schritte bezogen auf das godotengine/godot-Repository treffen ebenso auf das docs-Repository zu.

Warnung

The class reference's source files are in the Godot engine repository. We generate the Godot API section of this documentation from them. If you want to update the description of a class, its methods, or properties, read Beitrag zur Klassenreferenz.

Warnung

Sollten Sie die API-Reference bearbeiten wollen, beachten Sie dass dies nicht innerhalb des godot-docs-Repository erfolgt. Stattdessen sollten Sie die XML-Dateien unter doc/classes/* des Haupt-Repository von Godot bearbeiten. Diese Dateien werden später dafür eingesetzt, um die Godot-interne als auch die API-Referenz der Onlinedokumentation aktuell zu halten. Mehr dazu hier: Beitrag zur Klassenreferenz.

Der 'Edit on GitHub' Link

Wenn Sie die Dokumentation auf docs.godotengine.org lesen, wird oben rechts auf der Seite der Link Auf GitHub bearbeiten angezeigt. Sobald Sie ein GitHub-Konto erstellt haben, können Sie Änderungen wie folgt an einer Seite vorschlagen:

1. Drücken Sie auf den Edit on GitHub Knopf.

2. Klicken Sie auf der GitHub-Seite, zu der Sie weitergeleitet werden, auf das Stiftsymbol in der oberen rechten Ecke neben den Schaltflächen Raw, Blame und History. Es hat den Quickinfo-Text "Bearbeiten Sie die Datei in einem Fork dieses Projekts".

3. Führen Sie alle Änderungen durch, die Sie für diese Seite vornehmen möchten.

4. Fassen Sie die Änderungen zusammen, die Sie im Formular unten auf der Seite vorgenommen haben, und klicken Sie auf die Schaltfläche Dateiänderung vorschlagen wenn Sie fertig sind.

5. Klicken Sie in den folgenden Bildschirmen auf die Schaltfläche Pull-Anforderung erstellen, bis eine Meldung wie * Benutzername möchte 1 Commit in godotengine zusammenführen: Master von Benutzername: patch-6 * .

6. Ein Prüfer bewertet Ihre Änderungen und nimmt sie in die Dokumente auf, wenn sie akzeptabel sind. Möglicherweise werden Sie auch aufgefordert weitere Änderungen vorzunehmen, bevor diese aufgenommen werden.

Was macht eine gute Dokumentation aus?

Eine gute Dokumentation sollte klar, verständlich und objektiv sein, mit wohlgeformten Sätzen und, je nach Komplexität, sinnvollen Abschnitten und Unterkategorien. Siehe dazu auch die Richtlinien Dokumentation schreiben.

Wir unterscheiden Anleitungen von anderen Dokumentationsinhalten über folgende Definitionen:

• Anleitung: Ein Abschnitt mit dem Ziel, ein oder mehrere Konzepte, die im Editor oder in Skripten angewandt werden, anhand eines Beispiels zu veranschaulichen, um ein bestimmtes Lernziel zu erreichen (z.B. "Ein einfaches 2D-Pong-Spiel erstellen", "Kräfte auf ein Objekt wirken").

• Dokumentation: Eine Seite, auf der genau ein Konzept oder eine Funktionalität zur gleichen Zeit beschrieben wird und das, soweit möglich, bis ins kleinste Detail (z.B. die Auflistung der Methoden der Sprite-Klasse, oder eine Übersicht der Eingabeverwaltung in Godot).

Es ist Ihnen freigestellt welche Art von Dokumentation Sie schreiben möchten, solange Sie die folgenden Regeln respektieren (und die aus dem Repo).

Überschriften

Fangen Sie jede Seite stets mit der Überschrift an und einer internen Bezeichnung für den Sphinx-Verweis:

.. _doc_insert_your_title_here:

Insert your title here
======================

Der Verweis ermöglicht die Verknüpfung der Seite per :ref:-Tag, so würde etwa :ref:`doc_insert_your_title_here` auf die obige Beispielseite verlinken (man beachte den fehlenden Unterstrich im Verweis).

Außerdem vermeide CamelCase-Überschriften (die amerikanische Schreibweise): Das erste Wort sollte stets mit einem Großbuchstaben beginnen, während der Rest normal geschrieben wird. Hier ein gutes Beispiel:

• Hier Überschrift einfügen

Und das ist ein schlechtes Beispiel:

• Hier Überschrift Einfügen

Nur Node-Klassen-, Projekt-, Personennamen und sonstige grammatikalisch bedingte Fälle sollten großgeschrieben werden.

Übersetzen vorhandener Seiten

Sie können bei der Übersetzung der Godot-Dokumentation über unsere Hosted Weblate-Seite mithelfen.

Dann gibt es noch das offizielle Godot I18N-Repository wo man einsehen kann, wann die letzte Synchronisation stattgefunden hat.

Lizenz

Alle Beiträge werden unter der freizügigen Creative Commons Attribution 3.0-Lizenz (CC-BY-3.0) unter dem Namen „Juan Linietsky, Ariel Manzur and the Godot Engine community“ veröffentlicht.

Durch das Beitragen zu dieser Dokumentation im GitHub-Repository akzeptieren Sie die Veröffentlichung Ihrer Inhalte unter dieser Lizenz.