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 repositáře nette/docs
tento repositář naklonujete na svůj počítač
poté v příslušné větvi proveďte změny
zkontroluje 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 repositář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 repositář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.

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.