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] repozitáře [nette/docs |https://github.com/nette/docs] 2) tento repozitář [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) zkontrolujte přebytečné mezery v textu pomocí nástroje [Code-Checker |tools:code-checker] 5) 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 repozitář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 repozitář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. {{maintitle: Jak přispět do dokumentace Nette}} {{description: Přispívání do dokumentace pomáhá druhým porozumět frameworku. Jak psát pro nováčky, které jazykové verze upravovat a jak si text předem prohlédnout.}}

Jak přispět do dokumentace

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.

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

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 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 a případně využít některého z mnoha grafických klientů.

Dokumentaci upravujte tímto způsobem:

na GitHubu si vytvořte fork repozitáře nette/docs
tento repozitář naklonujete na svůj počítač
poté v příslušné větvi proveďte změny
zkontrolujte přebytečné mezery v textu pomocí nástroje Code-Checker
změny uložte (commitněte)
pokud jste se změnami spokojeni, odešlete (pushněte) je na GitHub do vašeho forku
odtud je odešlete do repozitáře nette/docs vytvořením 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 repozitáři 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.