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:

1. die direkte Sprache zu verwenden
2. präzise Handlungsverben zu nutzen
3. Verben zu vermeiden, die auf "-ing" enden (im englischen)
4. unnötige Adverben und Adjektive zu vermeiden.
5. 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)
6. explizite Referenzen zu nutzen
7. Use 's to show possession
8. eine Kommasetzung wie aus dem Duden

Es gibt 3 Arten Klassen zu beschreiben:

1. Geben Sie in der Kurzbeschreibung einen Überblick über den Node
2. Erwähnen Sie, welche Methoden zurückgegeben werden, wenn dies nützlich ist
3. 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):

1. obvious
2. simple
3. basic
4. easy
5. actual
6. just
7. clear
8. 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 dich 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

Do write constants and variables with dynamic typing:

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:

1. It's the only description in the "Create New Node" dialog.
2. 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.