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 the rules, and interesting details. Expanding into details can add unnecessary content, so keep the text concise and relevant to the topic at hand.

Wartbar

Beachten Sie, dass Blender regelmäßig neue Versionen hat. Versuchen Sie also, Inhalt zu schreiben, der nicht bei jeder kleinen vorgenommenen Änderung angepasst werden muss. Dies hilft auch der kleinen Dokumentationsgemeinschaft das Handbuch zu warten.

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.

  • Benutzen Sie amerikanisches Englisch (z.B.: modeling und nicht modelling, color und nicht colour), auch für die Zahlenformatierung (z.B. 2,718.28 und nicht 2718,28)(betrifft nur die .rst-Dateien). Für die Übersetzung verwenden Sie bitte Hochdeutsch.

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

  • Halten Sie die Sätze kurz und klar, so erhalten Sie leicht lesbaren, objektiven und treffenden Text.

  • 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:

  • Vermeiden Sie es, in der Ichform, über sich selbst oder Ihre eigenen Meinungen zu schreiben.

  • 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).“

    Diese Details sollte sich der Benutzer nicht merken und sie veralten schnell.

  • Bugs dürfen nicht dokumentiert werden.

    Zwischen Blender-Versionen werden oft Hunderte von Bugs behoben, deshalb ist es unrealistisch, auch nur einen Bruchteil davon im Handbuch zu referenzieren, während diese Liste aktuell gehalten wird.

    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.

  • Vermeiden Sie Produktplatzierungen, d.h. unnötiges Anpreisen von Software- oder Hardware-Marken. Bleiben Sie möglichst herstellerneutral.

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

  • Vermeiden Sie Aufzählungen ähnlicher Auswahlmöglichkeiten, wie z.B. jede Voreinstellung oder jede Bildrate eines Auswahlmenüs aufzulisten.

    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
   A method for distorting vertices based on an image.
   Similar to Bump Mapping, but instead operates on the mesh's actual geometry.
   This relies on the mesh having 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 type of object defined in terms of a line interpolated between Control Vertices.
   Available types of curves include Bézier and NURBS.