Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Inhaltliche Leitlinien

In diesem Dokument wird dargelegt, was in der offiziellen Dokumentation enthalten sein sollte. Im Folgenden finden Sie eine Reihe von Grundsätzen und Empfehlungen für die Erstellung barrierefreier Inhalte.

Wir wollen zwei Ziele erreichen:

  1. Sich in unsere Benutzer hineinversetzen. Wir sollten so schreiben, dass es für die Benutzer einfach ist, aus den Dokumenten zu lernen.

  2. Ein vollständiges Referenzhandbuch schreiben. Unser Ziel ist es nicht, Grundlagen des Programmierens zu vermitteln. Unser Ziel ist es vielmehr, eine Referenz für die Funktionsweise der Godot-Features zu erstellen.

Leitlinien und Grundsätze

Nachstehend finden Sie die Leitlinien, an die wir uns halten sollten. Sie sind jedoch keine festen Regeln: Manchmal erfordert ein Thema, dass man gegen eine oder mehrere von ihnen verstößt. Dennoch sollten wir uns bemühen, die beiden oben genannten Ziele zu erreichen.

Verfassen einer vollständigen und zugänglichen Dokumentation

Ein Feature existiert nicht, wenn es nicht dokumentiert ist. Wenn ein Benutzer keine Informationen über ein Feature und seine Funktionsweise finden kann, ist es für ihn nicht existent. Wir sollten sicherstellen, dass wir alles abdecken, was Godot tut.

Bemerkung

Wenn ein Engine-Feature hinzugefügt oder aktualisiert wird, muss das Dokumentationsteam darüber informiert werden. Mitwirkende sollten eine Issue im godot-docs-Repository erstellen, wenn ihre Arbeit gemergt wird und Dokumentation benötigt.

Bemühen Sie sich, die Länge der Dokumente unter 1000 Wörtern zu halten. Wenn eine Seite diesen Umfang überschreitet, sollten Sie in Erwägung ziehen, sie in zwei Teile aufzuteilen. Die Begrenzung des Seitenumfangs zwingt uns dazu, prägnant zu schreiben und umfangreiche Dokumente so aufzuteilen, dass sich jede Seite auf ein bestimmtes Problem konzentriert.

Jede Seite oder jeder Abschnitt einer Seite sollte klar angeben, welches Problem sie behandelt und was sie dem Benutzer beibringen wird. Die Benutzer müssen wissen, ob sie die richtige Anleitung für die Lösung der Probleme lesen, auf die sie stoßen. Anstatt die Überschrift "Signale" zu schreiben, sollten Sie beispielsweise "Mit Signalen auf Veränderungen reagieren" schreiben. Der zweite Titel verdeutlicht den Zweck von Signalen.

Bemerkung

Lange Abschnittsüberschriften führen zu langen Einträgen im Seitenmenü, was die Navigation umständlich machen kann. Versuchen Sie, die Überschriften auf maximal fünf Wörter zu beschränken.

Wenn die Seite bestimmte Kenntnisse über andere Godot-Features voraussetzt, erwähnen Sie dies und verweisen Sie auf die entsprechende Dokumentation. Eine Seite über Physik könnte beispielsweise Signale verwenden. In diesem Fall könnten Sie darauf hinweisen, dass das Signaltutorial eine Voraussetzung ist. Sie können auch auf andere Websites verweisen, die über den Umfang der Dokumentation hinausgehen. Sie könnten zum Beispiel auf eine Einführung in die Programmierung in der „Erste Schritte“-Anleitung verweisen oder auf eine Website, die mathematische Theorien lehrt, im Abschnitt Mathematik.

Begrenzen der kognitiven Belastung

Begrenzen Sie die kognitiven Belastung, die für das Lesen der Dokumentation erforderlich ist. Je einfacher und deutlicher die Sprache ist, die wir verwenden, desto effizienter können die Menschen lernen. Sie können dies tun, indem Sie:

  1. Möglichst nur ein neues Konzept auf einmal einführen.

  2. Einfaches Englisch verwenden, wie in unseren Schreibrichtlinien empfohlen.

  3. Ein oder mehrere konkreter Anwendungsbeispiele hinzufügen. Ziehen Sie ein reales Beispiel einem Beispiel vor, das Namen wie foo, bar oder baz verwendet.

Während viele Menschen komplexere Sprache und abstrakte Beispiele verstehen mögen, werden Sie andere verlieren. Eine verständliche Sprache und praktische Beispiele kommen allen zugute.

Versuchen Sie immer, sich in die Lage des Nutzers zu versetzen. Wenn wir etwas durch und durch verstehen, wird es für uns offensichtlich. Wir denken vielleicht nicht an Details, die für einen Neuling wichtig sind, aber gute Dokumentation holt den Benutzer dort ab, wo er ist. Wir sollten die Fähigkeiten oder den Verwendungszweck jedes Features in einer möglichst einfachen Sprache erklären.

Versuchen Sie sich daran zu erinnern, was Sie zuerst wissen mussten, als Sie das Feature oder Konzept kennenlernten. Welche neuen Begriffe mussten Sie lernen? Was hat Sie verwirrt? Was war am schwierigsten zu begreifen? Sie möchten, dass Ihre Arbeit von den Benutzern gelesen wird, und wir empfehlen, dass Sie üben, das Feature zu erklären, bevor Sie darüber schreiben.

Bemerkung

Die Grundlagen der Programmierung sind eine Voraussetzung für die Verwendung einer komplexen Engine wie Godot. Es ist akzeptabel, über Variablen, Funktionen oder Klassen zu sprechen. Wir sollten jedoch eine einfache Sprache gegenüber spezifischer Terminologie wie "Metaprogrammierung" bevorzugen. Wenn Sie präzise Begriffe verwenden müssen, sollten Sie diese auch definieren.