Sprievodca štýlom písania

Primárne ciele

Hlavné ciele tohto manuálu sú:

Zameranie na užívateľa

Manuál je určený pre ľudí znalých v oblasti v počítačovej grafiky, ktorí rozumejú základom 3D a/alebo poznajú iný 3D softvér. Aj keď sú niektoré oblasti počítačovej grafiky vysoko technické, netechnickí používatelia by mali mať tento návod k dispozícii na pochopenie.

Kompletnosť

Manuál poskytuje podrobný funkčný popis všetkých funkcií, nástrojov a možností v Blenderi. Aj keď pre každú z kľúčových oblastí Blenderu existuje zovšeobecnený zdroj pravdivosti, neznamená to, že musíme dokumentovať všetky podrobné detaily. Manuál by mal obsahovať informácie o tom, čo je funkcia, ako ju používať a aký je jej účel. V prípade potreby by sa malo poskytnúť viac základných informácií, aby sa lepšie pochopilo 3D zreťazené spracovanie.

Stručnosť

Počítačová grafika je neuveriteľne zaujímavá oblasť, s množstvom pravidiel, výnimiek z pravidiel a zaujímavých detailov. Rozoberaním do podrobností môžete pridať nepotrebný obsah, preto nech je váš text stručný a prislúchajúci k danej téme.

Udržiavanie

Pamätajte na to, že Blender je často vydávaný, takže skúste napísať obsah, ktorý nebude treba prerobiť v okamihu, keď dôjde k malej zmene. Toto tiež pomáha malej komunite dokumentácie udržiavať manuál.

Obsah usmernení

Z dôvodu zachovania konzistentného štýlu písania v manuáli nezabudnite na túto stránku a odchyľujte sa od nej, iba ak na to máte dobrý dôvod.

Pravidlá zásad:

  • Kontrola pravopisu je dôrazne odporúčaná.

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

  • Dbajte na gramatiku, správne znenie a používajte jednoduchú angličtinu.

  • Vety udržujte krátke a jasné, výsledkom čoho je ľahko čitateľný, objektívny a vecný text.

  • Dobrý nápad je uviesť aj dôvod prečo alebo ako by mohla byť voľba užitočná.

  • Ak si nie ste istí, ako funkcia funguje, opýtajte sa niekoho iného alebo spýtajte sa toho, kto ju vyvinul.

Je potrebné sa vyhnúť:

  • Vyvarujte sa písania z pohľadu prvej osoby, o sebe alebo svojich vlastných názoroch.

  • Nepoužívajte nejednoznačné slová a zbytočne neurčité, napr.:

    „Problém pravdepodobne vyrieši opätovné načítanie súboru.“
    „Väčšina ľudí túto možnosť nepoužíva, pretože …“

  • Neuvádzajte konkrétne podrobnosti, ako napríklad:

    „Blender má 23 rôznych druhov modifikátorov.“
    „Povolenie náhľadov pridá k veľkosti každého súboru zmesi 65536 bajtov (pokiaľ nie je komprimovaný).“

    Tieto podrobnosti nie sú užitočné na zapamätanie užívateľom a sú rýchlo zastaralé.

  • Vyhýbajte sa zdokumentovaniu chýb.

    Blender má medzi jednotlivými vydaniami často opravených 100 chýb, takže nie je reálne odkázať na ich zlomok z manuálu, pričom je tento zoznam aktuálny.

    Problémy, ktoré vývojári poznajú a nebudú vyriešené pred ďalším vydaním, je možné dokumentovať ako Známe limitácie. V niektorých prípadoch môže byť najlepšie zahrnúť ich do sekcie riešenie problémov.

  • Vyhýbajte sa umiestňovaniu produktov, t. j. zbytočnej propagácii značiek softvéru alebo hardvéru. Pokiaľ je to možné, udržiavajte obsah neutrálny voči predajcovi.

  • Ak existuje jednoduchší spôsob vysvetlenia, vyhnite sa technickému vysvetleniu matematickej/algoritmickej implementácie funkcie.

    (Napríklad vysvetlenie toho, ako fungujú algoritmy vyhladzovania sietí, je zbytočné, ale typy zmiešavania uzla Zmiešanie potrebujú matematické vysvetlenie.)

  • Vyvarujte sa opakovaniu veľkých častí textu. Jednoducho to vysvetlite raz a od tej doby sa na toto vysvetlenie odvolávajte.

    Všeobecnú terminológiu zvážte definovaním výrazu :term: v slovníku.

  • Vyvarujte sa výpočtu podobných možností, ako je zoznam všetkých prednastavených alebo všetkých snímkových frekvencií vo vybranej ponuke.

    Ich obsah možno zhrnúť alebo jednoducho vynechať. – Takéto zoznamy zobrazujú iba to, čo je už v rozhraní zrejmé a nakoniec je na čítanie a údržbu priveľa textu.

  • Vyhnite sa dokumentovaniu zmien v Blenderi medzi vydaniami, na čo slúžia poznámky k vydaniu. Potrebujeme len zdokumentovať aktuálny stav Blenderu.

  • Pokiaľ je jednotka, v ktorej je nameraná hodnota, nejasná a nepredvídateľná, nie je potrebné ju spomínať.

  • Nekopírujte jednoducho tipy z Blenderu. – Ľudia prichádzajú do manuálu sa dozvedieť viac, ako poskytuje užívateľské rozhranie.

    Ako poslednú možnosť môžete pridať komentár (ktorý sa nezobrazuje na stránke HTML, ale je vhodný pre ostatných editorov):

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

Slovník

Táto časť sa konkrétne týka sekcie Slovník, kde sú definované bežné pojmy v Blenderi a počítačovej grafike.

Pravidlá zásad:

  • Pred poskytnutím ďalších informácií definujte pojem.

  • Pred definíciou nepoužívajte konštrukcie ako „je to“ alebo „xyz je“.

  • Vyvarujte sa opakovaniu výrazu okamžite alebo jeho použitiu v definícii.

  • Nepridávajte výrazy, ktoré sa nenachádzajú v rozhraní Blenderu ani v manuáli.

  • Vyvarujte sa príliš dlhým vstupom. Ak je potrebné vysvetlenie zložitého výrazu, doplňte ho externými odkazmi.

  • Vyvarujte sa duplicite dokumentácie; ak je vysvetlenie pojmu hlavným zameraním v inej časti príručky (napr. ak je pojmom názov nástroja), buď iba odkazujte na túto časť, alebo sa vyhnite úplnému vytvoreniu záznamu v slovníku.

  • Na koniec sa majú pridať URL odkazy, formátované nasledovne, napr .:

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

Príklady

Tento záznam:

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.

Namiesto toho by bolo vhodnejšie to napísať takto, s uvedením definície na prvom mieste:

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.

Tento záznam:

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

Bolo by vhodnejšie takto, aby sa zabránilo okamžitému opakovaniu termínu:

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

Tento záznam:

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

Bolo by vhodnejšie takto, vyhnúť sa „to je“:

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