Richtlinien Dokumentation schreiben¶
Die Godot-Gemeinschaft ist international, Benutzer kommen aus der ganzen Welt. Einige von ihnen sind jung und viele sprechen nicht Englisch als Muttersprache. Deshalb müssen wir alles in einer klaren und gemeinsamen Sprache schreiben. Für die Klassenreferenz ist es das Ziel, sie für alle leicht lesbar und präzise zu machen.
Zusammenfassend, versuche immer:
- die direkte Sprache zu verwenden
- präzise Handlungsverben zu nutzen
- Verben zu vermeiden, die auf "-ing" enden (im englischen)
- unnötige Adverben und Adjektive zu vermeiden.
- diese 8 Wörter zu vermeiden: offensichtlich, einfach, grundlegend, leicht, tatsächlich, bloß, klar und jedoch (obvious, simple, basic, easy, actual, just, clear, and however)
- explizite Referenzen zu nutzen
- Use 's to show possession
- eine Kommasetzung wie aus dem Duden
Es gibt 3 Arten Klassen zu beschreiben:
- Geben Sie in der Kurzbeschreibung einen Überblick über den Node
- Erwähnen Sie, welche Methoden zurückgegeben werden, wenn dies nützlich ist
- Verwenden Sie "falls wahr", um Boolesche Werte zu beschreiben
Bemerkung
Die Aufgabe eines technischen Redakteurs ist es, so viele Informationen wie möglich in möglichst kleine und klare Sätze zu packen. Diese Richtlinien helfen Ihnen dabei, auf dieses Ziel hinzuarbeiten.
7 Regeln für eine klare Sprache (gültig für Englisch)¶
die direkte Sprache zu verwenden¶
Verwenden Sie nach Möglichkeit die direkte Form. Nehmen Sie die Klassen, Methoden und Konstanten, die Sie als Thema beschreiben als Subjekt. Es ist natürlicher in der passiven Form zu schreiben, aber es ist schwieriger zu lesen und erzeugt längere Sätze.
Passiv:
The man **was bitten** by the dog.
Activ:
The dog bit the man.
Verwenden Sie nicht die passive Form:
void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.
Verwenden Sie den Namen des Nodes als Substantiv:
void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.
präzise Handlungsverben zu nutzen¶
Favor precise yet common verbs over generic ones like make
, set
,
and any expression you can replace with a single word.
Wiederholen Sie nicht den Namen der Methode. Es wird bereits angegeben, dass der Pivot-Wert auf einen neuen Wert gesetzt wird:
void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]
Erklären Sie was die Konsequenz dieses "Set" ist: Verwenden Sie präzise Verben wie "Ort", "Position", "Drehen", "Verblassen" usw.
void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]
Verben zu vermeiden, die auf "-ing" enden (im englischen)¶
The progressive forms describe continuous actions. E.g. "is calling", "is moving".
Verwenden Sie nicht die progressive Form für sofortige Änderungen.
Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]
Verwenden Sie einfache Gegenwart, Vergangenheit oder Zukunft.
Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]
Exception: If the subject is not clear, replacing "ing" verbs is not an improvement. For example, in the previous sentence, "it replaces" would not make much sense where "replacing" currently is.
Sie können im englischen die "progressive tense" (Verlaufsform der Gegenwart) verwenden, um zeitlich kontinuierliche Aktionen zu beschreiben. Alles wie Animationen oder Koroutinen.
Tipp
Verbs can turn into adjectival nouns with -ing. This is not a
conjugation, so you may use them: the remaining movement
,
the missing file
, etc.
Entfernen Sie unnötige Adverbien und Adjektive¶
Schreiben Sie so wenig Adjektive und Adverbien wie möglich. Verwenden Sie sie nur, wenn sie der Beschreibung wichtige Informationen hinzufügen.
Verwenden Sie keine redundanten oder bedeutungslosen Adverbien. Wörter, die die Dokumentation verlängern, aber keine Informationen hinzufügen:
**Basically** a big texture [...]
Schreiben Sie kurze Sätze in einer einfachen, beschreibenden Sprache:
A big texture [...]
Verbannen Sie diese 8 Wörter¶
Benutzen Sie niemals diese 8 verbotenen Wörter (im englischen):
- obvious
- simple
- basic
- easy
- actual
- just
- clear
- however (some uses)
Das Erstellen und Programmieren von Spielen ist nicht einfach, und für jemanden, der zum ersten Mal die Verwendung der API lernt, ist nichts einfach. Andere Wörter in der Liste, wie "nur" oder "tatsächlich", fügen dem Satz keine Informationen hinzu. Verwenden Sie auch keine entsprechenden Adverbien: offensichtlich, einfach, im Grunde, leicht, tatsächlich, klar.
Beispiel: Die gesperrten Wörter verlängern die Beschreibung und lenken die Aufmerksamkeit von den wichtigsten Informationen ab:
**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.
entferne sie:
**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.
"Einfach" hilft nie. Denken Sie daran, dass für andere Benutzer alles komplex sein oder sie frustrieren kann. Es gibt nichts Schöneres als ein gutes altes es ist einfach um Sie zusammenzucken zu lassen. Hier ist die alte kurze Beschreibung, der erste Satz auf der Seite des Timer-Nodes:
**Timer**
A **simple** Timer node.
Erklären Sie stattdessen, was der Node tut:
**Timer**
Calls a function of your choice after a certain duration.
Verwenden Sie nicht "basic", es ist zu vage:
**Vector3**
Vector class, which performs **basic** 3D vector math operations.
Verwenden Sie die kurze Beschreibung, um einen Überblick über den Node zu erhalten:
**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.
explizite Referenzen zu nutzen¶
Bevorzugen Sie explizite Referenzen gegenüber impliziten.
Verwenden Sie keine Wörter wie "Ersteres", "Letzteres" usw. Sie sind im Englischen nicht die gebräuchlichsten und erfordern, dass Sie die Referenz überprüfen.
[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.
Wiederholen Sie Wörter. Sie beseitigen alle Unklarheiten:
[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.
Wenn Sie denselben Variablennamen drei- oder viermal wiederholen müssen, müssen Sie Ihre Beschreibung wahrscheinlich neu formulieren.
Use 's to show possession¶
Vermeiden Sie "Die Milch der Kuh". Es fühlt sich auf Englisch unnatürlich an. Schreiben Sie stattdessen "Die Kuhmilch".
schreibe nicht "von X":
The region **of the AtlasTexture that is** used.
Benutzen Sie 's
. Damit können Sie das Hauptthema an den Anfang des Satzes setzen und es kurz halten:
The **AtlasTexture's** used region.
Verwenden Sie das Oxford-Komma, für alles Aufzählungen¶
Aus dem Oxford-Wörterbuch:
Das 'Oxford-Komma' ist ein optionales Komma vor dem Wort 'und' am Ende einer Liste: Wir verkaufen Bücher, Videos, und Zeitschriften.
[...] Nicht alle Autoren und Verleger verwenden es, aber es kann die Bedeutung eines Satzes verdeutlichen, wenn die Elemente in einer Liste keine einzelnen Wörter sind: Diese Elemente sind in Schwarz und Weiß, Rot und Gelb, sowie Blau und Grün verfügbar.
Lassen Sie das letzte Element einer Liste nicht ohne Komma:
Create a KinematicBody2D node, a CollisionShape2D node and a sprite node.
Fügen Sie ein Komma vor und oder oder für das letzte Element einer Liste mit mehr als zwei Elementen ein.
Create a KinematicBody2D node, a CollisionShape2D node, and a sprite node.
Wie man Methoden und Klassen schreibt¶
Gegenüberstellung dynamischer und statischer Typisierung¶
Die Codebeispiele in der Dokumentation sollten einem einheitlichen Stil folgen, um die Benutzer nicht zu verwirren. Da statische Typhinweise eine optionale Funktion von GDScript sind, haben wir uns entschieden, beim Schreiben von dynamischem Code zu bleiben. Dies führt dazu, dass GDScript präzise und zugänglich geschrieben wird.
Die Ausnahme bilden Themen, die Benutzern statische Typisierungskonzepte erläutern.
Fügen Sie keinen Typhinweis mit einem Doppelpunkt oder durch Casting hinzu:
const MainAttack := preload("res://fire_attack.gd")
var hit_points := 5
var name: String = "Bob"
var body_sprite := $Sprite as Sprite
Schreiben Sie Konstanten und Variablen mit dynamischer Typisierung:
const MainAttack = preload("res://fire_attack.gd")
var hit_points = 5
var name = "Bob"
var body_sprite = $Sprite
Schreiben Sie keine Funktionen mit abgeleiteten Argumenten oder Rückgabetypen:
func choose(arguments: PoolStringArray) -> String:
# Chooses one of the arguments from array with equal chances
randomize()
var size := arguments.size()
var choice: int = randi() % size
return arguments[choice]
Vor- und Nachteile von dynamischer Typisierung:
func choose(arguments):
# Chooses one of the arguments from array with equal chances
randomize()
var size = arguments.size()
var choice = randi() % size
return arguments[choice]
Verwenden Sie gegebenenfalls reale Codebeispiele¶
Real-world examples are more accessible to beginners than abstract foos
and
bars
. You can also copy them directly from your game projects, ensuring that
any code snippet compiles without errors.
Writing var speed = 10
rather than var my_var = 10
allows beginners to
understand code better. It gives them a frame of reference as to where they
could use the code snippets in a live project.
Schreiben Sie keine erfundenen Beispiele:
onready var a = preload("res://MyPath")
onready var my_node = $MyNode
func foo():
# Do stuff
Schreiben Sie konkrete Beispiele:
onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
onready var audio_player = $Audio/AudioStreamPlayer
func play_shooting_sound():
audio_player.stream = sfx_player_gun
audio_player.play()
Of course, there are times when using real-world examples is impractical. In
those situations, you should still avoid using names such as my_var
,
foo()
or my_func()
and consider more meaningful names for your examples.
Geben Sie in der Kurzbeschreibung einen Überblick über den Node¶
The brief description is the reference's most important sentence. It's the user's first contact with a node:
- It's the only description in the "Create New Node" dialog.
- It's at the top of every page in the reference
The brief description should explain the node's role and its functionality, in up to 200 characters.
Schreiben Sie keine winzigen und vage Zusammenfassungen:
**Node2D**
Base node for 2D system.
Geben Sie einen Überblick über die Funktionalität des Nodes:
**Node2D**
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
Verwenden Sie die vollständige Beschreibung des Nodes, um weitere Informationen und, falls möglich, ein Codebeispiel bereitzustellen.
Erwähnen Sie, welche Methoden zurückgegeben werden, wenn dies nützlich ist¶
Some methods return important values. Describe them at the end of the
description, ideally on a new line. No need to mention the return values
for any method whose name starts with set
or get
.
Verwenden Sie nicht die passive Form:
Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.
Verwenden Sie immer "Returns".
Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.
Notice the exception to the "direct voice" rule: with the move method,
an external collider can influence the method and the body that calls
move
. In this case, you can use the passive voice.
Verwenden Sie "falls wahr", um Boolesche Werte zu beschreiben¶
For boolean member variables, always use if true
and/or
if false
, to stay explicit. Controls whether or not
may be
ambiguous and won't work for every member variable.
Also, surround boolean values, variable names and methods with [code][/code]
.
Fangen Sie mit "Falls Wahr" an:
Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.
Verwende [code]
um Argumente¶
In the class reference, always surround arguments with [code][/code]
. In the
documentation and in Godot, it will display like this
. When you edit XML
files in the Godot repository, replace existing arguments written like 'this' or
`this` with [code]this[/code]
.
Allgemeines Vokabular für Godots Dokumentation¶
Die Entwickler haben einige spezifische Wörter ausgewählt, um auf Bereiche der Benutzeroberfläche zu verweisen. Sie werden in den Quellen und in der Dokumentation verwendet, und Sie sollten sie immer anstelle von Synonymen verwenden, damit die Benutzer wissen, wovon Sie sprechen.

Übersicht über die Benutzeroberfläche und das allgemeine Vokabular
In der oberen linken Ecke des Editors befinden sich die Hauptmenüs
. In der Mitte ändern die Schaltflächen den Arbeitsbereich
. Und zusammen sind die Schaltflächen oben rechts die Spieletest-Schaltflächen
. Der Bereich in der Mitte, der den 2D- oder 3D-Raum anzeigt, ist das Ansichtsfenster
. Oben finden Sie eine Liste der Werkzeuge
innerhalb der Symbolleiste
.
Die Registerkarten oder andockbaren Bedienfelder auf beiden Seiten des Ansichtsfensters sind Docks
. Sie haben das Dateisystem Dock
, das Szenen Dock
, das Ihren Szenenbaum enthält, das Import Dock
, das Node Dock
und den Inspektor
oder Inspektor Dock
. Mit dem Standardlayout können Sie diese andockbaren Dock als Registerkarten
bezeichnen: die Szenen-Registerkarte
, die Node-Registerkarte
...
Die Animation, der Debugger usw. am unteren Rand des Ansichtsfensters sind Panele
. Zusammen bilden sie die untersten Panele
.
Faltbare Bereiche des Inspektors sind Abschnitte
. Die übergeordneten Klassennamen des Nodes, die Sie nicht falten können, sind Klassen
, z. die KinematicBody2D Klasse
und einzelne Zeilen mit Schlüssel-Wert-Paaren sind Eigenschaften
, z.B. Position
oder Farbe modulieren
sind beides Eigenschaften
.
Tastenkürzel Richtlinien¶
Tastatur- und Mausverknüpfungen sollten das Tag :kbd:
verwenden, mit dem sich Verknüpfungen vom Rest des Textes und des Inline-Codes abheben können. Verwenden Sie das kompakte Formular für Modifizierertasten (Strg/Cmd) anstelle der buchstabierten Form(Steuerung/Command). Verwenden Sie für Kombinationen das Symbol +
mit einem Leerzeichen auf beiden Seiten des Symbols.
Stellen Sie sicher, dass Sie Verknüpfungen erwähnen, die sich unter MacOS von anderen Plattformen unterscheiden. Unter MacOS ersetzt Cmd
häufig Strg
in Tastaturkürzeln.
Versuchen Sie, die Verknüpfung so gut wie möglich in Sätze zu integrieren. Hier einige Beispiele, bei denen das Tag :kbd:
zur besseren Sichtbarkeit unverändert bleibt:
- Drücken Sie
:kbd:`Ctrl + Alt + T`
um das Bedienfeld umzuschalten (:kbd:`Cmd + Alt + T`
auf MacOS). - Halten Sie
:kbd:`Space`
und die linke Maustaste gedrückt, um im 2D-Editor zu schwenken. - Drücken Sie
:kbd:`Shift + Pfeil nach oben`
um den Node um 8 Pixel nach oben zu bewegen.
Richtlinien für Bildbeiträge¶
Ein wesentlicher Teil der Dokumentation sind Bilder, und es gibt mehrere wichtige Richtlinien, die befolgt werden müssen.
Erstens sollten Sie beim Erstellen von Screenshots immer das Standardthema und den Standardtext des Editors verwenden.
Um das Erscheinungsbild von 3D Screenshots zu verbessern, verwenden Sie 4 × MSAA, aktivieren Sie die anisotrope Filterung der Projekttexturen und stellen Sie die Qualität des anisotropen Filters in den Projekteinstellungen auf 16 × ein.
Die Größe der Screenshots sollte 1920 × 1080 nicht überschreiten, um ein schnelles Laden bei langsameren Verbindungen zu gewährleisten.
When you need to highlight an area of the editor to show something, like a button or option, use a 2 pixel-thick yellow outline without a bevel. If the outline is on a dark background, the outline should be yellow so it can be easily seen by colorblind people. Please do not use red as it won't be visible for some users.
Before you add or replace any images in the documentation, they should be run through a PNG compressor to save size. You can use the lossless OxiPNG compressor included in Squoosh for this purpose. For heavier images, consider using a lossy compressor like pngquant. With it, almost no image quality is lost during compression.
Bemerkung
The program pngquant must be installed locally as it's not available in Squoosh.