Jak přispět do dokumentace

**************************

.[perex]

Přispívání do dokumentace je jednou z nejpřínosnějších činností, neboť pomáháte druhým porozumět frameworku.

Jak psát?

---------

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

- Začněte od jednoduchého a obecného. K pokročilejším tématům přejděte až na konci

- Snažte se věc co nejlépe vysvětlit. Zkuste například téma nejprve vysvětlit kolegovi

- 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é. Každý kód otestujte

- Buďte struční - co napíšete, zkraťte na polovinu. A pak klidně ještě jednou

- Šetřete zvýrazňovači všeho druhu, od tučného písma po rámečky jako `.[note]`

- V kódech dodržujte [Coding Standard]

Osvojte si také [syntax]. Pro náhled článku během jeho psaní můžete použít [editor s náhledem |https://editor.nette.org/].

Jazykové mutace

---------------

Primárním jazykem je angličtina, vaše změny by tedy měly být v češtině i angličtině. Pokud angličtina není vaší silnou stránkou, použijte [DeepL Translator |https://www.deepl.com/translator] a ostatní vám text zkontrolují.

Překlad do ostatních jazyků bude proveden automaticky po schválení a doladění vaší úpravy.

Triviální úpravy

----------------

Pro přispívání do dokumentace je nezbytné mít účet na [GitHub|https://github.com].

Nejjednodušší způsob, jak provést drobnou změnu v dokumentaci, je využít odkazy na konci každé stránky:

- *Ukaž na GitHubu* otevře zdrojovou podobu dané stránky na GitHubu. Poté stačí stisknout tlačítko `E` a můžete začít editovat (je nutné být na GitHubu přihlášený)

- *Otevři náhled* otevře editor, kde rovnou vidíte i výslednou vizuální podobu

Protože [editor s náhledem |https://editor.nette.org/] nemá možnost ukládat změny přímo na GitHub, je nutné po dokončení úprav zdrojový text zkopírovat do schránky (tlačítkem *Copy to clipboard*) a poté jej vložit do editoru na GitHubu. Pod editačním polem je formulář pro odeslání. Zde nezapomeňte stručně shrnout a vysvětlit důvod vaší úpravy. Po odeslání vznikne tzv. pull request (PR), který je možné dále editovat.

Větší úpravy

------------

Vhodnější, než využít rozhraní GitHubu, je být obeznámen se základy práce s verzovacím systémem Git. Pokud neovládáte práci s Gitem, můžete se podívat na průvodce [git - the simple guide |https://rogerdudler.github.io/git-guide/] a případně využít některého z mnoha [grafických klientů |https://git-scm.com/downloads/guis].

Dokumentaci upravujte tímto způsobem:

1) na GitHubu si vytvořte [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] repositáře [nette/docs |https://github.com/nette/docs]

2) tento repositář [naklonujete |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] na svůj počítač

3) poté v [příslušné větvi |#Struktura dokumentace] proveďte změny

4) zkontroluje přebytečné mezery v textu pomocí nástroje [Code-Checker |tools:code-checker]

4) změny uložte (commitněte)

6) pokud jste se změnami spokojeni, odešlete (pushněte) je na GitHub do vašeho forku

7) odtud je odešlete do repositáře `nette/docs` vytvořením [pull request|https://help.github.com/articles/creating-a-pull-request] (PR)

Je běžné, že budete dostávat komentáře s připomínkami. Sledujte navrhované změny a zapracujte je. Navrhované změny přidejte jako nové commity a znovu odešlete na GitHub. Nikdy nevytvářejte kvůli úpravě pull requestu nový pull request.

Struktura dokumentace

---------------------

Celá dokumentace je umístěna na GitHubu v repositáři [nette/docs |https://github.com/nette/docs]. Aktuální verze je v masteru, starší verze jsou umístěny ve větvích jako `doc-3.x`, `doc-2.x`.

Obsah každé větve se dělí do hlavních složek představujících jednotlivé oblasti dokumentace. Například `application/` odpovídá https://doc.nette.org/cs/application, `latte/` odpovídá https://latte.nette.org atd. Každá tato složka obsahuje podsložky představující jazykové mutace (`cs`, `en`, ...) a případně podsložku `files` s obrázky, které je možné do stránek v dokumentaci vkládat.