Psaní dokumentace

Přispívání do dokumentace je jednou z mnoha cest, jak lze pomoci Nette. Zároveň jde také o jednu z nejpřínosnějších činností, neboť pomáháte druhým frameworku porozumět.

Jak psát?

Dokumentace je určena především lidem, kteří se s tématem teprve seznamují. Proto by měla splňovat několik důležitých bodů:

• Při psaní začněte od jednoduchého a obecného, k pokročilejším tématům přejděte až na konci.
• Uvádějte jen ty informace, které uživatel skutečně k danému tématu potřebuje vědět.
• Ověřte si, že vaše informace jsou skutečně pravdivé. Před uvedením kódu příklad nejprve vyzkoušejte.
• Buďte struční – co napíšete, zkraťte na polovinu. A pak klidně ještě jednou.
• Snažte se věc co nejlépe vysvětlit. Zkuste například téma nejprve vysvětlit kolegovi.

Tyto body mějte na paměti po celou dobu psaní. Další tipy naleznete v článku Píšeme pro web. Dokumentace je psaná v Texy!, proto se naučte jeho syntax. Pro náhled článku během jeho psání můžete použít editor dokumentace na adrese https://editor.nette.org/.

Kromě výše uvedených bodů také dodržujte následující zásady:

• Primárním jazykem je angličtina, vaše změny by tedy měly být v obou jazycích. Pokud angličtina není vaší silnou stránkou, použijte Google Translator a ostatní vám váš text zkontrolují.
• V textu dokumentace spíše „mykáme“ a jsme zdvořilí.
• V příkladech dodržujte Coding Standard.
• Názvy proměnných, tříd a metod pište anglicky.
• Namespaces stačí uvádět při první zmínce.
• Kód se snažte formátovat tak, aby se nezobrazovaly posuvníky.
• Šetřete zvýrazňovači všeho druhu, od tučného písma po rámečky .[note].
• Z dokumentace se odkazujte pouze na dokumentaci nebo www.

Struktura dokumentace

Celá dokumentace je umístěna na GitHubu v repositáři nette/docs. Tento repositář je rozdělen do větví podle verze dokumentace, například větev doc-2.1 obsahuje dokumentaci pro verzi 2.1.

Každá větev je pak rozdělena do několika složek:

• cs a en: obsahuje soubory dokumentace pro jednotlivé jazykové verze.
• files: obrázky, které je možné do stránek v dokumentaci vkládat.

Cesta k souboru bez přípony odpovídá URL adrese stránky v dokumentaci. Soubor cs/quickstart/single-post.texy tedy bude mít v příslušné verzi české dokumentace adresu quickstart/single-post.

Při vytváření stránek dbejte na následující pravidla:

• Používejte maximálně 2 úrovně URL a jazyk, např. en/forms/rendering.texy.
• Volte stručná URL, např. stránka „Atomic Operations“ je na doc.nette.org/en/atomicity.
• Používejte anglická URL, shodná napříč všemi jazyky, např. doc.nette.org/cs/forms/rendering a doc.nette.org/en/forms/rendering.

Přispívání do dokumentace

Pro přispívání do dokumentace je nutné mít účet na github.com a znát základy práce s verzovacím systémem git. Pokud s gitem nekamarádíte, můžete se podívat na rychlý návod: git – the simple guide, nebo si pomoci některým z mnoha grafických nástrojů: GIT – GUI clients.

Pokud se rozhodnete do dokumentace přispět, nejdříve si vytvořte fork již zmíněného repositáře nette/docs a repositář si naklonujte na svůj počítač. Poté v příslušné větvi proveďte změny, změnu commitněte, pushněte do svého repositáře na github.com a pošlete pull request do původního repositáře nette/docs. Pamatujte, že hlavním jazykem dokumentace je angličtina, změny proto provádějte v obou jazycích.

Při psaní dokumentace se také dodržuje coding standard. Před každým pull requestem, nejlépe před pushem do repozitáře, je dobré si spustit nette/code-checker, který nám zkontroluje všechny coding standardy.