Psaní dokumentace

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

Rychlé úpravy

Nejjednodušší způsob, jak upravit text 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, který je možné dále editovat.

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ů:

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 jej nejprve otestujte.
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.
Šetřete zvýrazňovači všeho druhu, od tučného písma po rámečky jako .[note].

Tyto body mějte na paměti po celou dobu psaní. Osvojte si také syntax. Pro náhled článku během jeho psaní můžete použít editor s náhledem.

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 DeepL Translator a ostatní vám váš text zkontrolují.
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.
Z dokumentace se odkazujte pouze na dokumentaci nebo www.

Přispívání do dokumentace

Pro přispívání do dokumentace je nutné mít účet na GitHub. Jednoduché změny můžete provádět přímo v jeho rozhraní.

Vhodnější je ale 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.

Dokumentaci upravujte tak, že se vytvoříte fork repositáře nette/docs a ten si naklonujete na 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 a pošlete pull request do původního repositáře nette/docs.

Před každým pull requestem je dobré si spustit Code-Checker, který zkontroluje přebytečné mezery v textu.

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.