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:

  1. na GitHubu si vytvořte fork repositáře nette/docs
  2. tento repositář naklonujete na svůj počítač
  3. poté v příslušné větvi proveďte změny
  4. zkontroluje přebytečné mezery v textu pomocí nástroje 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 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.