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. Use the active voice

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. Verwenden Sie es, um Besitz anzuzeigen

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.

Siehe auch

See the content guidelines for information on the types of documentation you can write in the official documentation.

7 Regeln für eine klare Sprache (gültig für Englisch)

Use the active voice

Use the active voice when possible. Take the classes, methods, and constants you describe as the subject. It's natural to write using the passive voice, but it's harder to read and produces longer sentences.

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

Bevorzugen Sie präzise, aber gebräuchliche Verben gegenüber generischen Verben wie make, set und allen Ausdrücken, die Sie durch ein einziges Wort ersetzen können.

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)

Die progressiven Formen beschreiben kontinuierliche Aktionen. z.B. "ruft", "bewegt sich".

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. [...]

Do use simple present, past, or future.

Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]

Ausnahme: Wenn das Thema nicht eindeutig ist, hat das Ersetzen von "ing"-Verben keine Verbesserung. Zum Beispiel würde im vorherigen Satz "es ersetzt" nicht viel Sinn machen, wo jetzt "ersetzen" steht.

Sie können im englischen die "progressive tense" (Verlaufsform der Gegenwart) verwenden, um zeitlich kontinuierliche Aktionen zu beschreiben. Alles wie Animationen oder Koroutinen.

Tipp

Verben können sich mit -ing in adjektivische Substantive verwandeln. Dies ist keine Konjugation, Sie können sie also verwenden: ,,die verbleibende Bewegung", ,,die fehlende Datei", usw.

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 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.

Verwenden Sie es, um Besitz anzuzeigen

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: PackedStringArray) -> 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

Beispiele aus der realen Welt sind für Anfänger leichter zugänglich als abstrakte foos und bars. Sie können sie auch direkt aus Ihren Spielprojekten kopieren und so sicherstellen, dass jeder Codeschnipsel ohne Fehler kompiliert wird.

Wenn Sie var speed = 10 statt var my_var = 10 schreiben, können Anfänger den Code besser verstehen. Es gibt ihnen einen Bezugsrahmen, in dem sie die Codeschnipsel in einem Live-Projekt verwenden können.

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()

Natürlich gibt es Situationen, in denen die Verwendung von Beispielen aus der realen Welt unpraktisch ist. In solchen Situationen sollten Sie trotzdem Namen wie my_var, foo() oder my_func() vermeiden und sich sinnvollere Namen für Ihre Beispiele überlegen.

Geben Sie in der Kurzbeschreibung einen Überblick über den Node

Die Kurzbeschreibung ist der wichtigste Satz der Referenz. Er ist der erste Kontakt des Benutzers mit einem Node:

1. Es ist die einzige Beschreibung im Dialogfeld "Neuen Node erstellen".

2. Es befindet sich oben auf jeder Seite in der Referenz

Die Kurzbeschreibung sollte die Rolle des Nodes und seine Funktionalität in bis zu 200 Zeichen erklären.

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

Einige Methoden geben wichtige Werte zurück. Beschreiben Sie diese am Ende der Beschreibung, am besten in einer neuen Zeile. Bei allen Methoden, deren Name mit set oder get beginnt, müssen Sie die Rückgabewerte nicht erwähnen.

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.

Beachten Sie die Ausnahme von der "direct voice"-Regel: Bei der move-Methode kann ein externer Collider die Methode und den Körper, der move aufruft, beeinflussen. In diesem Fall können Sie die passive Stimme verwenden.

Verwenden Sie "falls wahr", um Boolesche Werte zu beschreiben

Für boolesche Member-Variablen sollten Sie immer if true und/oder if false verwenden, um eindeutig zu bleiben. Kontrolliert, ob oder ob nicht kann mehrdeutig sein und wird nicht für jede Member-Variable funktionieren.

Umgeben Sie außerdem boolesche Werte, Variablennamen und Methoden mit [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 der Klassenreferenz umgeben Sie Argumente immer mit [code][/code]. In der Dokumentation und in Godot wird es wie this angezeigt. Wenn Sie XML-Dateien im Godot-Repository bearbeiten, ersetzen Sie vorhandene Argumente, die wie 'this' oder 'this' geschrieben sind, durch [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 Bereiche auf beiden Seiten des Ansichtsfensters sind Docks. Sie haben das FileSystem-Dock und Szenen-Dock, welches Ihren Szenenbaum enthält, das Import-Dock, Node-Dock und Inspector oder Inspector-Dock. Im Standard-Layout können Sie die Docks mit Registerkarten Registerkarten nennen: die Szenen-Registerkarte, Knoten-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.

Wenn Sie einen Bereich des Editors hervorheben müssen, um etwas zu zeigen, z. B. eine Schaltfläche oder eine Option, verwenden Sie eine 2 Pixel dicke gelbe Kontur ohne Abschrägung. Wenn sich der Umriss auf einem dunklen Hintergrund befindet, sollte der Umriss gelb sein, damit er von Farbenblinden leicht gesehen werden kann. Bitte verwenden Sie kein Rot, da es für manche Benutzer nicht sichtbar ist.

Bevor Sie Bilder in der Dokumentation hinzufügen oder ersetzen, sollten diese durch einen PNG-Kompressor laufen, um Größe zu sparen. Sie können zu diesem Zweck den verlustfreien OxiPNG-Kompressor verwenden, der in Squoosh enthalten ist. Für größere Bilder sollten Sie einen verlustbehafteten Kompressor wie pngquant verwenden. Mit ihm geht bei der Komprimierung fast keine Bildqualität verloren.

Bemerkung

Das Programm pngquant muss lokal installiert werden, da es in Squoosh nicht verfügbar ist.