Vodič za pisanje

Primarni cilji

The main goals for this manual are as follows:

Z ozirom na uporabnika

The manual is written for people educated in computer graphics, who understand the basics of 3D and/or know other 3D software. While some areas of computer graphics are highly technical, this manual shall be kept understandable by non-technical users.

Celovitost

The manual provides detailed functional description of all features, tools and options in Blender. While there is a canonical source of truth for each of Blender’s key areas, this does not mean we have to document every small detail. The manual should provide information on what a feature is, how to use it, and its purpose. More background information should be provided when necessary to give deeper understanding of a 3D pipeline.

Jedrnatost

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.

Vzdrževanje

Imejte v mislih, da se Blender pogosto posodablja, zato poskusite pisati tako, da ne bo treba besedila spreminjati, čim se zgodi majhna sprememba v programu. To pomaga majhni dokumentacijski skupnosti, da lahko vzdržuje priročnik.

Vsebinske smernice

Da bo način pisanja po vsem priročniku približno enak, si oglejte, kako je ta stran napisana v angleščini, in jo imejte za vzor. Takega načina pisanja se držite, razen ko imate zelo dober razlog.

Priporočila:

  • Uporaba črkovalnika je močno priporočena.

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

  • Pazite na slovnično pravilnost, pravilno ubeseditev in uporabite preprosto angleščino.

  • Ohranite stavke kratke in razumljive, da bo besedilo lažje berljivo, objektivno in jasno.

  • Dobro je pripisati, zakaj in kako bi se dalo določeno funkcijo uporabiti.

  • Če niste prepričani, kako kakšna funkcija deluje, vprašajte koga drugega ali poizvedite, kdo jo je razvil, in se pozanimajte pri njem.

Izogibajte se:

  • Ne pišite v prvi osebi, o sebi ali lastnih prepričanjih.

  • Izogibajte se hinavskim besedam in nepotrebni nerazločnosti, npr.:

    „Ponovno nalaganje datoteke bo verjetno odpravilo težavo“
    „Večina ljudi te možnosti ne uporablja, ker …“

  • Vzdržite se dodajanje specifičnih podrobnosti, kot so:

    „Blender ima 23 različnih vrst modifikatorjev.“
    „Omogočanje predogledov doda k velikosti vsake datoteke .blend 65536 bajtov (razen če je stisnjena).“

    Teh podrobnosti si uporabnikom ni treba zapomniti in hitro lahko postanejo zastarele.

  • Ne dokumentirajte napak.

    Blender z vsakim izidom odpravi na stotine napak, zato jih je nepotrebno navajati v priročniku, če naj ga vzdržujemo v koraku s časom.

    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.

  • Izogibajte se navajanju izdelkov, t. j. nepotrebnega promoviranja ponudnikov programske ali strojne opreme. Vsebino ohranite nevtralno, kar se tiče prodajalcev.

  • Izogibajte se razlagam o matematičnih/algoritemskih implementacij funkcij, če obstaja preprostejša razlaga.

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

  • Izogibajte se ponavljanju večjih delov besedila. Razložite enkrat samkrat in se kasneje navežite na tisto razlago.

    Izraze, ki sodijo v splošno terminologijo, definirajte :izraz: v slovarčku.

  • Izogibajte se naštevanju podobnih možnosti, kot je navajanje vsake prednastavitve ali vsake hitrosti sličic v izbirnem meniju.

    Njihovo vsebino lahko povzamete ali preprosto izpustite. – Takšni seznami samo ponovijo tisto, kar je že očitno v uporabniškem vmesniku, in so na koncu samo kup besedila, ki ga je težko brati in vzdrževati.

  • Izogibajte se dokumentiranja sprememb v Blenderju med izidi. Temu je namenjen seznam novosti (ang. release notes). Dokumentirati je treba le trenutno stanje programa.

  • Razen če je enota, v kateri je neka vrednost izmerjena, nejasna ali nezanesljiva, je ni potrebno omenjati.

  • Ne kopirajte namigov iz pojavnih oken (ang. tooltips) v Blenderju. – Ljudje si prebirajo priročnik, da bi se naučili več, kot nudijo razlage v uporabniškem vmesniku.

    Če ne gre drugače, lahko dodate komentar (ki ni viden na strani HTML, je pa uporaben za druge urejevalce):

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

Slovarček

Ta razdelek je namenjen izključno slovarčku, kjer definiramo pogosto uporabljene izraze v Blenderju in računalniški grafiki.

Priporočila:

  • Definirajte izraz, preden podate več informacij.

  • Ne uporabljajte raznih „it is“ ali „xyz is“ pred definicijo.

  • Ne uporabljajte izraza v njegovi razlagi.

  • Ne dodajajte izrazov, ki jih ni v uporabniškem vmesniku programa ali priročniku.

  • Ne dodajajte predolgih vnosov. Če je potrebna razlaga zapletenega izraza, priložite raje zunanjo povezavo.

  • Ne podvajajte dokumentacije; če je razlaga izraza glavnina drugega razdelka v priročniku (npr. če je izraz ime orodja), raje navedite povezavo do tega razdelka ali se v celoti izognite vnašanju izraza v slovarček.

  • URL sklici naj bodo dodani na koncu, v sledečem formatu:

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

Primeri

Ta vnos:

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.

Naj bo raje napisan takole, prva naj bo definicija:

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.

Ta vnos:

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

Naj bo napisan tako, da v definiciji ne bo ponavljanja izraza:

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

Ta vnos:

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

Naj bo napisan takole, brez „it is“:

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