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ť. Existuje mnoho pravidiel, výnimiek z týchto pravidiel a zaujímavých detailov. Rozširovanie detailov však môže pridať zbytočný obsah; preto udržujte text stručný a relevantný pre koncového užívateľa.

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í

V záujme zachovania jednotného štýlu písania v manuáli majte na pamäti túto stránku a odchýľte sa od nej len vtedy, keď na to máte dobrý dôvod. V prípade pochybností sa poraďte s tímom dokumentácie na Blender Chate.

Pravidlá zásad:

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

  • Používajte americkú angličtinu (napr: modeling a nie modelling, color a nie colour) aj na formátovanie čísel (napr. 2,718.28 a nie 2 718,28).

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

  • Vety sú krátke a jasné.

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

  • Súbory RST by mali byť pokryté v stĺpci 120. Žiadny riadok textu by nemal presiahnuť túto dĺžku.

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 údaje nie sú pre užívateľov užitočné a rýchlo zastarávajú.

  • Vyhýbajte sa zdokumentovaniu chýb.

    V Blenderi sa medzi jednotlivými vydaniami často opravujú stovky chýb, takže sa nedá očakávať, že príručka bude držať krok.

    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.

  • Vyhnite sa uvádzaniu všetkých možností v ponuke, ako sú napríklad snímkové frekvencie.

    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 popisy z Blenderu.

    Ľudia chodia do manuálu, aby sa dozvedeli viac, ako poskytuje užívateľské rozhranie. Ako poslednú možnosť môžete pridať komentár (ktorý sa na stránke HTML nezobrazuje, ale je užitočný pre iných editorov):

    .. TODO how does this tool work? ask Joe Blogg.

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
   Distorts vertices with an image.
   Similar to Bump Mapping, but operates on the mesh's geometry.
   The mesh must have 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 line interpolated between Control Vertices.
   Common types include Bézier and NURBS.