Guide för skrivstil¶

Primära mål¶

De huvudsakliga målen för denna manual är följande:

Användarfokuserad: Manualen är skriven för personer med utbildning i datorgrafik, som förstår grunderna i 3D och/eller känner till andra 3D-program. Även om vissa områden inom datorgrafik är mycket tekniska, ska den här handboken vara begriplig för icke-tekniska användare.
Färdig: Manualen ger en detaljerad funktionsbeskrivning av alla funktioner, verktyg och alternativ i Blender. Även om det finns en kanonisk källa till sanning för vart och ett av Blenders nyckelområden, betyder det inte att vi måste dokumentera varje liten detalj. Manualen ska ge information om vad en funktion är, hur man använder den och dess syfte. Mer bakgrundsinformation bör ges när det behövs för att ge en djupare förståelse av en 3D-pipeline.
Kortfattad: Datorgrafik är ett otroligt intressant område. Det finns många regler, undantag från dessa regler och intressanta detaljer. Att gå in på detaljer kan dock leda till onödigt innehåll; håll därför texten kortfattad och relevant för slutanvändaren.
Underhållsbar: Tänk på att Blender ofta släpps i nya versioner, så försök att skriva innehåll som inte behöver göras om så fort någon liten ändring görs. Detta hjälper också en liten dokumentationsgrupp att underhålla manualen.

Riktlinjer för innehåll¶

För att upprätthålla en konsekvent skrivstil i manualen, vänligen ha denna sida i åtanke och avvik endast från den när du har en god anledning att göra det. Om du är osäker, kolla med dokumentationsteamet på Blender Chat.

Tumregler:

Stavningskontroll rekommenderas starkt.
Använd amerikansk engelska (t.ex. modeling och inte modelling, color och inte colour) även för att formatera siffror (t.ex. 2,718.28 och inte 2 718,28).
Tänk på grammatik, lämpliga formuleringar och använd enkel engelska.
Håll meningarna korta och tydliga.
Det är en bra idé att inkludera varför eller hur ett alternativ kan vara användbart.
Om du är osäker på hur en funktion fungerar kan du fråga någon annan eller ta reda på vem som har utvecklat den och fråga dem.
RST-filer ska brytas vid kolumn 120. Inga textrader bör överstiga den längden.

Bör undvikas:

Undvik att skriva i första person, om dig själv eller om dina egna åsikter.
Undvik ”snömosord” <https://en.wikipedia.org/wiki/Weasel_word>`__ och att vara onödigt vag, t.ex:

”Att ladda om filen kommer förmodligen att lösa problemet”

”De flesta människor använder inte detta alternativ eftersom …”
Undvik att inkludera specifika detaljer som t.ex:

”Blender har 23 olika typer av modifierare.”

”Om du aktiverar förhandsgranskningar ökar storleken på varje blend-fil med 65536 byte (om den inte är komprimerad).”

Dessa uppgifter är inte användbara för användarna och blir snabbt inaktuella.
Undvik att dokumentera buggar.

Blender har ofta hundratals buggar som fixas mellan utgåvorna, så manualen kan inte förväntas hålla jämna steg.

Problem som är kända av utvecklarna och som inte kommer att lösas före nästa version kan dokumenteras som Kända begränsningar. I vissa fall kan det vara bäst att inkludera dem i avsnittet troubleshooting.
Undvik produktplaceringar, t.ex. onödig marknadsföring av mjuk- eller hårdvarumärken. Håll innehållet leverantörsneutralt där så är möjligt.
Undvik tekniska förklaringar om den matematiska/algoritmiska implementeringen av en funktion om det finns ett enklare sätt att förklara det.

(Det är t.ex. onödigt att förklara hur algoritmer för utjämning av mesh fungerar, men blandningstyperna i en Mix-nod behöver en matematisk förklaring)
Undvik upprepning av stora delar av texten. Förklara det bara en gång och hänvisa sedan till den förklaringen.

För allmän terminologi kan du överväga att definiera en :term: i ordlistan.
Undvik att lista alla alternativ i en meny, t.ex. bildfrekvenser.

Deras innehåll kan sammanfattas eller helt enkelt utelämnas. Sådana listor visar bara det som redan är uppenbart i gränssnittet och blir till slut en massa text att läsa och underhålla.
Undvik att dokumentera förändringar i Blender mellan releaser, det är vad release notes är till för. Vi behöver bara dokumentera det nuvarande tillståndet för Blender.
Om inte den enhet som ett värde mäts i är obegriplig och oförutsägbar behöver den inte nämnas.
Kopiera inte bara verktygstipsen från Blender.

Folk kommer till manualen för att lära sig mer än vad som tillhandahålls av användargränssnittet. Som en sista utväg kan du lägga till en kommentar (som inte visas på HTML-sidan, men som är användbar för andra redigerare):
```
.. TODO how does this tool work? ask Joe Blogg.
```

Ordlista¶

Det här avsnittet handlar specifikt om avsnittet Ordlista, där vi definierar vanliga termer inom Blender och datorgrafik.

Tumregler:

Definiera termen innan du ger någon ytterligare information.
Undvik att använda konstruktioner som ”det är” eller ”xyz är” före definitionen.
Undvik att upprepa termen direkt eller att använda den i definitionen.
Undvik att lägga till termer som inte finns i Blenders gränssnitt eller i manualen.
Undvik alltför långa poster. Om det behövs en förklaring av en komplex term kan du komplettera med externa länkar.
Undvik dubblering av dokumentation; om förklaringen av termen är huvudfokus i ett annat avsnitt i handboken (t.ex. om termen är namnet på ett verktyg), kan du antingen bara länka till det avsnittet eller helt undvika att skapa en ordlistepost.
URL-referenser ska läggas till i slutet, formaterade på följande sätt, t.ex:
```
See also `OpenGL <https://en.wikipedia.org/wiki/OpenGL>`__ on Wikipedia.
```

Exempel¶

Denna post:

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.

Skulle skrivas så här istället, med en definition först:

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

Denna post:

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

Skulle skrivas mer så här, för att undvika den omedelbara upprepningen av termen:

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

Denna post:

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

Skulle skrivas mer så här, undvika ”det är”:

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