Leitfaden zum Schreibstil

Primäre Ziele

Die Hauptziele für dieses Handbuch sind folgende:

Benutzerbezogen

Das Handbuch richtet sich an Personen mit einer Ausbildung in Computergrafik, die die Grundlagen von 3D verstehen und/oder andere 3D-Software kennen. Obwohl einige Bereiche der Computergrafik sehr technisch sind, soll dieses Handbuch auch für nicht-technische Benutzer verständlich gehalten werden.

Vollständig

Das Handbuch enthält eine detaillierte Funktionsbeschreibung aller Features, Tools und Optionen von Blender. Obwohl es für jeden der Schlüsselbereiche von Blender eine einzige Quelle der Wahrheit gibt, bedeutet dies nicht, dass wir jedes kleinste Detail dokumentieren müssen. Das Handbuch sollte darüber informieren, was ein Feature ist, wie es zu benutzen ist und welchen Zweck es erfüllt. Wenn nötig, sollten mehr Hintergrundinformationen zur Verfügung gestellt werden, um ein tieferes Verständnis einer 3D-Pipeline zu ermöglichen.

Prägnant

Computer graphics is an incredibly interesting field. There are many rules, exceptions to those rules, and interesting details. However, expanding into details can add unnecessary content; therefore, keep the text concise and relevant to the end user.

Wartbar

Keep in mind that Blender has frequent releases, so try to write content that will not have to be redone the moment some small change is made. This also helps a small documentation community maintain the manual.

Inhaltsleitfaden

Um einen durchgehenden Schreibstil im Handbuch zu gewährleisten, behalten Sie bitte diese Seite im Hinterkopf und weichen Sie nur dann davon ab, wenn Sie einen guten Grund haben, dies zu tun.

Faustregeln:

  • Eine Rechtschreibprüfung wird dringend empfohlen.

  • Use American English (e.g: modeling and not modelling, color and not colour) also for formatting numbers (e.g: 2,718.28 and not 2 718,28).

  • Achten Sie auf Grammatik, korrekte Wortwahl und benutzen Sie einfaches Deutsch.

  • Keep sentences short and clear.

  • Es ist eine gute Idee, zu erwähnen, warum oder wie eine Option nützlich sein könnte.

  • Wenn Sie sich nicht sicher sind, wie ein Feature funktioniert, fragen Sie jemand anderen oder finden Sie heraus, wer es entwickelt hat und fragen Sie ihn.

Was zu vermeiden ist:

  • Avoid writing in the first person perspective, about yourself, or about your own opinions.

  • Vermeiden Sie Wieselwörter und unnötig vage zu sein, z.B:

    „Erneutes Laden der Datei wird das Problem vielleicht beheben“
    „Die meisten Leute verwenden diese Option nicht, da …“

  • Vermeiden Sie die Angabe spezifischer Details wie:

    „Blender hat 23 verschiedene Modifier-Arten.“
    „Aktivieren der Vorschau fügt 65536 Bytes zur Größe der Blender-Datei hinzu (sofern sie nicht komprimiert ist).“

    These details are not useful for users and become quickly outdated.

  • Bugs dürfen nicht dokumentiert werden.

    Blender often has hundreds of bugs fixed between releases, so the manual cannot be expected to keep up.

    Issues that are known to the developers and are not going to be resolved before the next release can be documented as Known Limitations. In some cases, it may be best to include them in the troubleshooting section.

  • Avoid product placements, e.g. unnecessarily promoting software or hardware brands. Keep content vendor-neutral where possible.

  • Vermeiden Sie technische Erklärungen über die mathematische/algorithmische Implementierung eines Features, wenn es einen einfacheren Weg gibt, es zu erklären.

    (es ist z. B. unnötig zu erklären, wie Mesh-Smoothing-Algorithmen funktionieren, aber die Blending-Typen eines Mix-Nodes benötigen eine mathematische Erklärung).

  • Vermeiden Sie Wiederholungen langer Textpassagen. Erklären Sie es einfach einmal und verweisen Sie dann auf diese Erklärung.

    Für allgemeine Fachausdrücke sollten Sie es in Betracht ziehen, einen Begriff (:term:) im Glossar zu definieren.

  • Avoid listing every option in a menu, such as frame rates.

    Deren Inhalt könnte zusammengefasst oder einfach weggelassen werden. – Solche Listen geben nur das bereits in der Bedienoberfläche offensichtliche an und enden als viel zu lesender und zu wartender Text.

  • Dokumentieren Sie keine Änderungen zwischen Versionen, dafür gibt es die Versionshinweise. Es ist nur der aktuellen Stand von Blender zu dokumentieren.

  • Sofern die Einheit, in der ein Wert gemessen wird, nicht unklar und unvorhersehbar ist, braucht sie nicht erwähnt zu werden.

  • Kopieren Sie nicht einfach die Tooltip-Texte von Blender. – Das Handbuch wird schließlich benutzt, um mehr zu erfahren, als die Benutzeroberfläche hergibt.

    Als letzten Ausweg können Sie einen Kommentar hinzufügen, der nicht in der HTML-Seite angezeigt wird, aber hilfreich für andere Bearbeiter ist:

    .. TODO, how does this tool work? ask Joe Blogg's.

Glossar

In diesem Abschnitt geht es speziell um das Glossar, in dem gängige Begriffe von Blender und Computergrafik definiert werden.

Faustregeln:

  • Definieren Sie den Begriff, bevor Sie weitere Informationen eingeben.

  • Vermeiden Sie Ausdrücke wie „Das ist“ oder „xyz ist“ vor der Definition.

  • Vermeiden Sie es, den Begriff sofort zu wiederholen oder ihn in der Definition zu verwenden.

  • Fügen Sie keine Begriffe hinzu, die nicht in Blenders Benutzeroberfläche oder im Handbuch zu finden sind.

  • Vermeiden Sie überlange Einträge. Wenn eine Erklärung eines komplexen Begriffs erforderlich ist, ergänzen Sie ihn durch externe Links.

  • Vermeiden Sie doppelte Dokumentation; wenn die Erklärung des Begriffs im Mittelpunkt eines anderen Abschnitts des Handbuchs steht (z.B. wenn es sich um den Namen eines Werkzeugs handelt), dann verlinken Sie einfach auf diesen Abschnitt, anstatt einen ganzen Glossareintrag zu erstellen.

  • URL-Verweise sollten am Schluss mit folgender Formatierung gegeben werden:

    See also `OpenGL <https://en.wikipedia.org/wiki/OpenGL>`__ on Wikipedia.

Beispiele

Dieser Eintrag:

Displacement Mapping
   Uses a grayscale heightmap, like Bump Mapping,
   but the image is used to physically move the vertices of the mesh at render time.
   This is of course only useful if the mesh has large amounts of vertices.

Sollte stattdessen so geschrieben werden, dass die Definition am Anfang steht:

Displacement Mapping
   Distorts vertices with an image.
   Similar to Bump Mapping, but operates on the mesh's geometry.
   The mesh must have enough geometry.

Dieser Eintrag:

Doppler Effect
   The Doppler effect is the change in pitch that occurs
   when a sound has a velocity relative to the listener.

Sollte besser ohne die sofortige Wiederholung des Begriffs geschrieben werden:

Doppler Effect
   Perceived change in pitch that occurs
   when the source of a sound is moving relative to the listener.

Dieser Eintrag:

Curve
   It is a class of objects.
   In Blender there are Bézier curves and NURBS curves.

Sollte besser ohne das „it is“ geschrieben werden:

Curve
   A line interpolated between Control Vertices.
   Common types include Bézier and NURBS.