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

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

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

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

    (so ist z.B. die Erklärung der Arbeitsweise von Kantenglättungsalgorithmen unnötig, wohingegen die Mischungstypen eines ‚‘Mix‘‚-Knotens eine mathematische Erklärung benötigen.)

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

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

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

  • 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

Dieses Kapitel ist speziell über das Glossar, in dem die allgemeinen Begriffe von Blender und Computergrafik definiert werden.

Daumenregeln:

  • Definieren Sie den Term bevor Sie weitergehende Informationen geben.

  • Vermeiden Sie Ausdrücke mit „Das ist“ oder „xyz ist“ vor der 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.