Schrijfstijlgids

Primaire Doelen

De belangrijkste doelen voor deze handleiding zijn als volgt:

Gericht op de Eindgebruiker

De handleiding is geschreven voor mensen die bekend zijn met computer graphics, die de basisprincipes van 3D begrijpen en/of andere 3D-software kennen. Hoewel sommige gebieden van computer graphics zeer technisch zijn, moet deze handleiding begrijpelijk zijn voor niet-technische gebruikers.

Compleet

De handleiding biedt een gedetailleerde functionele beschrijving van alle functies, tools en opties in Blender. Hoewel er veel informatie te vinden is voor elk onderdeel in Blender, betekent dit niet dat we elk klein detail moeten documenteren. De handleiding moet informatie verstrekken over wat een functie is, hoe deze te gebruiken en waarvoor deze voor dient. Meer achtergrondinformatie zou kunnen worden verstrekt, wanneer dat nodig is, om een dieper begrip van een 3D-pijplijn te geven.

Beknopt

Computer graphics is een buitengewoon interessant vakgebied, met veel regels, uitzonderingen op de regels en interessante details. Uitweiden in details kan onnodige inhoud toevoegen, dus houd de tekst beknopt en relevant.

Gemakkelijk te onderhouden

Houd er rekening mee dat Blender vaak nieuwe versies heeft, dus probeer inhoud te schrijven die niet opnieuw hoeft te worden gedaan zodra er een kleine wijziging wordt aangebracht. Dit helpt ook een kleine documentatiegroep om de handleiding te onderhouden.

Inhoudsrichtlijnen

Om een consistente schrijfstijl binnen de handleiding te handhaven, houd deze pagina dan in gedachten en wijkt er alleen van af wanneer je daar een goede reden voor hebt.

Vuistregels:

  • Spellingscontrole wordt sterk aanbevolen.

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

  • Let op grammatica, passend taalgebruik en gebruik eenvoudig Engels.

  • Houd zinnen kort en duidelijk, waardoor de tekst gemakkelijk te lezen, objectief en to the point is.

  • Het is een goed idee om te vermelden waarom of hoe een optie nuttig kan zijn.

  • Als je niet zeker bent over hoe een functie werkt, vraag dan iemand anders om hulp of zoek uit wie het heeft ontwikkeld en vraag het aan hen.

Te vermijden:

  • Vermijd het schrijven in de eerste persoon, over jezelf of je eigen meningen.

  • Vermijd “weasel words” en onnodige vaagheid, bijvoorbeeld:

    “Het opnieuw laden van het bestand zal waarschijnlijk het probleem oplossen.”
    “De meeste mensen gebruiken deze optie niet omdat …”

  • Vermijd het opnemen van specifieke details zoals:

    “Blender heeft 23 verschillende soorten modifiers.”
    “Het inschakelen van voorbeelden voegt 65536 bytes toe aan de grootte van elk blend-bestand (tenzij het gecomprimeerd is).”

    Deze details zijn niet nuttig voor gebruikers om te onthouden en zijn snel verouderd.

  • Vermijd het documenteren van bugs.

    Blender heeft honderden bugs opgelost tussen releases, dus het is niet realistisch om zelfs maar een fractie ervan te vermelden in de handleiding, terwijl deze lijst up-to-date wordt gehouden.

    Problemen die bekend zijn bij de ontwikkelaars en niet zullen worden opgelost vóór de volgende release, kunnen worden gedocumenteerd als Known Limitations. In sommige gevallen is het wellicht het beste om ze op te nemen in de probleemoplossing sectie.

  • Vermijd productplaatsingen, oftewel het onnodig promoten van software- of hardwaremerken. Houd de inhoud zo veel mogelijk neutraal ten opzichte van leveranciers.

  • Vermijd technische uitleg over de wiskundige/algoritmische implementatie van een functie als er een eenvoudigere manier is om het uit te leggen.

    (Bijvoorbeeld, uitleggen hoe mesh-smoothing algoritmes werken is onnodig, maar de mengtypen van een Mix-node vereisen wel een wiskundige uitleg.)

  • Vermijd herhaling van grote delen tekst. Leg het gewoon een keer uit en verwijs vervolgens naar die uitleg.

    Voor algemene terminologie, overweeg het definiëren van een “:term:” in het glossary.

  • Vermijd opsommingen van vergelijkbare opties, zoals het opsommen van elke preset of elke framesnelheid in een selectiemenu.

    Deze inhoud kan worden samengevat of eenvoudig worden weggelaten. Dergelijke lijsten tonen alleen wat al duidelijk is in de interface en wordt uiteindelijk te veel tekst om te lezen en te onderhouden.

  • Vermijd het documenteren van wijzigingen in Blender tussen releases, daar zijn de release-opmerkingen voor. We hoeven alleen de huidige status van Blender te documenteren.

  • Tenzij de eenheid waarin een waarde wordt gemeten obscuur en onvoorspelbaar is, is er geen noodzaak om deze te vermelden.

  • Kopieer niet simpelweg de tooltips van Blender. Mensen komen naar de handleiding om meer te leren dan wat wordt geboden door de gebruikersinterface.

    Als laatste redmiddel kunt u een opmerking toevoegen (die niet wordt weergegeven op de HTML-pagina, maar handig is voor andere redacteuren):

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

Begrippenlijst

Deze sectie gaat specifiek over het Glossary onderdeel, waarin we veelvoorkomende termen in Blender en computergraphics definiëren.

Vuistregels:

  • Definieer de term voordat je verdere informatie verstrekt.

  • Vermijd het gebruik van constructies zoals “het is” of “xyz is” vóór de definitie.

  • Vermijd het direct herhalen van de term of het gebruiken ervan in de definitie.

  • Vermijd het toevoegen van termen die niet te vinden zijn in de interface van Blender of in de handleiding.

  • Vermijd overdreven lange vermeldingen. Als er uitleg nodig is voor een complexe term, vul dan aan met externe links.

  • Vermijd het dupliceren van documentatie; als het uitleggen van de term de primaire focus is van een ander gedeelte van de handleiding (bijvoorbeeld als de term de naam van een tool is), link dan alleen naar dat gedeelte, of maak helemaal geen glossary-item aan.

  • URL-verwijzingen moeten aan het einde worden toegevoegd, opgemaakt als volgt, bijvoorbeeld:

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

Examples (Voorbeelden)

Deze vermelding:

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.

Zou in plaats daarvan als volgt worden geschreven, met eerst een definitie:

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.

Deze vermelding:

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

Zou meer als dit worden geschreven, waarbij de onmiddellijke herhaling van de term wordt vermeden:

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

Deze vermelding:

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

Zou meer als dit worden geschreven, waarbij “it is” wordt vermeden:

Curve
   A type of object defined in terms of a line interpolated between Control Vertices.
   Available types of curves include Bézier and NURBS.