Psaní dokumentace
Přispívání do dokumentace je jednou z mnoha cest, jak lze pomoci Nette. Zároveň jde také o jednu z nejpřínosnějších činností, neboť pomáháte druhým frameworku porozumět.
Jak psát?
Dokumentace je určena především lidem, kteří se s tématem teprve 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 příklad nejprve vyzkoušejte.
- 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.
Tyto body mějte na paměti po celou dobu psaní. Další tipy naleznete v článku Píšeme pro web. Dokumentace je psaná v Texy!, proto se naučte jeho syntax. Pro náhled článku během jeho psaní můžete použít editor dokumentace na adrese https://editor.nette.org/.
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 textu dokumentace spíše „mykáme“ a jsme zdvořilí.
- 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.
- Šetřete zvýrazňovači všeho druhu, od tučného písma po rámečky
.[note]
. - Z dokumentace se odkazujte pouze na dokumentaci nebo
www
.
Struktura dokumentace
Celá dokumentace je umístěna na GitHubu v repositáři nette/docs. Tento
repositář je rozdělen do větví podle verze dokumentace, například větev doc-3.1
obsahuje dokumentaci pro
verzi 3.1. A dále je tu větev nette.org
, ve které je obsah ostatních subdomén webu nette.org.
Každá větev je pak rozdělena do několika složek:
cs
aen
: obsahuje soubory dokumentace pro jednotlivé jazykové verzefiles
: obrázky, které je možné do stránek v dokumentaci vkládat
Cesta k souboru bez přípony odpovídá URL adrese stránky v dokumentaci. Soubor
cs/quickstart/single-post.texy
tedy bude mít adresu doc.nette.org/cs/quickstart/single-post
.
Přispívání do dokumentace
Pro přispívání do dokumentace je nutné mít účet na GitHub a 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.
Jednoduché změny můžete provádět přímo v rozhraní GitHubu. Vhodnější je ale vytvořit si fork repositáře nette/docs a ten si naklonovat 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
. Pamatujte, že hlavním jazykem dokumentace je angličtina, změny proto provádějte v obou
jazycích.
Před každým pull requestem je dobré si spustit Code-Checker, který nám zkontroluje přebytečné mezery v textu.
- Dokumentace
- Contributing
- Psaní dokumentace