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.