Richtlinien Dokumentation

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

How to contribute

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, sieh Dir die Pull request workflow-Seite an. Die meisten der dort beschriebenen Schritte bezogen auf das godotengine/godot-Repository treffen ebenso auf das docs-Repository zu.

Die README.md-Datei enthält alle Informationen, die Du benötigst, um loszulegen; lies es bitte durch. Insbesondere enthält sie Tipps und Tricks sowie Links zur Referenz der StructuredText-Bezeichnungssprache.

Warnung

Solltest Du die API-Reference bearbeiten wollen, beachte dass dies nicht innerhalb des godot-docs-Repository erfolgt. Stattdessen solltest Du 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: Contribute to the Class Reference.

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 sei Dir freigestellt, welche Art von Dokumentation Du schreiben möchtest solange Du die folgenden Regeln respektierst (und die aus dem Repo).

Überschriften

Fange 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 Sphinx-Verweis erlaubt es, die Seite per :ref:-Tag zu verlinken, 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

Du kannst bei der Übersetzung der Godot-Dokumentation über unsere Hosted Weblate-Seite mithelfen.

Translation state

Dann gibt es noch das offizielle Godot I18N-Repository. wo Du einsehen kannst, 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 akzeptierst Du die Veröffentlichung Deiner Inhalte unter dieser Lizenz.