Leitfaden zum Schreibstil

Primäre Ziele

Die Hauptziele für dieses Handbuch sind die folgenden.

Benutzerbezogen
Obwohl einige Bereiche der Computergrafik sehr technisch sind, soll dieses Handbuch auch für fachfremde (non-technical) Benutzer verständlich gehalten werden.
Vollständig
Sodass eine umfassende und verlässliche Quelle für Informationen über Blenders Hauptbereiche entsteht. Dies bedeutet nicht, dass wir jedes kleine Detail dokumentieren müssen, aber die Benutzer sollen nicht anderswo suchen müssen, um den Zweck der Hauptmerkmale zu finden.
Prägnant
Computergrafik ist ein unglaublich interessantes Gebiet, es gibt viele Regeln, Ausnahmen zu den Regeln und interessante Details. In die Details einzudringen kann unnötigen Inhalt hinzufügen, halten Sie den Text kurz, klar und für das betreffende Thema relevant.
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 der kleinen Dokumentationsgemeinschaft das Handbuch zu warten.

Inhaltsleitfaden

Um einen durchgehenden Schreibstil im Handbuch zu gewährleisten verinnerlichen Sie diese Seite und weichen nur davon ab, wenn es dafür gute Gründe gibt.

Daumenregeln:

  • 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.
  • Halten Sie die Sätze kurz und klar, so erhalten Sie leicht lesbaren, objektiven und treffenden Text.
  • Anmerken, wann oder warum eine Option hilfreich sein könnte ist eine gute Idee.
  • Wenn Sie bezüglich der Arbeitsweise eines Programmteiles unsicher sein, fragen Sie jemand anders oder finden Sie heraus, wer ihn entwickelt hat und fragen Sie sie.

Vermieden werden sollten:

  • Vermeiden Sie es aus der ich-Perspektive, über Sie selbst oder Ihre 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.“
    „Enabling previews adds 65536 bytes to the size of each blend-file (unless it is compressed).“

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

  • Dokumentieren Sie möglichst keine Fehler.

    Zwischen Versionen von Blender werden oft hunderte Fehler behoben. Es ist also nicht realistisch auch nur auf einen kleinen Bruchteil im Handbuch einzugehen und diese Liste aktuell zu halten.

    Probleme, die den Entwicklern bekannt sind und nicht vor der nächsten Version gelöst werden, können als Bekannte Einschränkungen dokumentiert werden. In einigen Fällen ist es das Beste, sie in das Kapitel Fehlerbehebung aufzunehmen.

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

  • Vermeiden Sie technische Erklärungen der mathematischen/algorithmischen Umsetzung eines Programmteils wenn es einen einfacheren Weg etwas zu erklären.

    (E.g. explaining how mesh smoothing algorithms work is unnecessary, but the blending types of a mix node do need a mathematical explanation.)

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

    Überlegen Sie für allgemeine Begriffsdefinitionen einen Begriff (:term:) im Glossar zu definieren.

  • Avoid enumerations of similar options, such as listing every preset or every frame rate in a select menu.

    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.

  • Die Einheit, in der ein Wert gemessen wird, muss nicht zwingend angegeben werden, es sei denn sie ist unklar oder unvorhersehbar.

  • Do not simply copy the tooltips from Blender. – People will come to the manual to learn more than is provided by the UI.

    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

This section is specifically about the Glossary section, where we define common terms in Blender and computer graphics.

Daumenregeln:

  • Definieren Sie den Term bevor Sie weitergehende Informationen geben.

  • Avoid using constructs such as „it is“ or „xyz is“ before the definition.

  • Vermeiden Sie den Begriff in der Definition, speziell als erstes Wort.

  • Definieren Sie keine Begriffe, die nicht in der Benutzeroberfläche oder dem Handbuch von Blender zu finden sind.

  • Vermeiden Sie lange Einträge. Wenn eine Erklärung eines komplexen Begriffes benötigt wird, ergänzen Sie externe Links.

  • Vermeiden Sie doppelte Dokumentation, Wenn ein anderes Kapitel den Hauptfokus auf einem Begriff hat (z.B. weil er der Name eines Werkzeugs ist), verlinken Sie auf diesen Artikel oder vermeiden Sie einen Eintrag im Glossar ganz.

  • URL-Verweise sollten am Ende in der folgenden 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 so geschrieben werden, mit der Definition am Anfang.:

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 Wiederholung des Begriffes 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.