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 psání 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 Google 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-2.1
obsahuje dokumentaci pro
verzi 2.1.
Každá větev je pak rozdělena do několika složek:
cs
aen
: obsahuje soubory dokumentace pro jednotlivé jazykové verze.files
: 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 v příslušné verzi české dokumentace adresu
quickstart/single-post
.
Při vytváření stránek dbejte na následující pravidla:
- Používejte maximálně 2 úrovně URL a jazyk, např.
en/forms/rendering.texy
. - Volte stručná URL, např. stránka „Atomic Operations“ je na
doc.nette.org/en/atomicity
. - Používejte anglická URL, shodná napříč všemi jazyky, např.
doc.nette.org/cs/forms/rendering
adoc.nette.org/en/forms/rendering
.
Přispívání do dokumentace
Pro přispívání do dokumentace je nutné mít účet na github.com 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.
Pokud se rozhodnete do dokumentace přispět, nejdříve si vytvořte fork již zmíněného repositáře nette/docs a repositář si naklonujte na svůj 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.com 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ři psaní dokumentace se také dodržuje coding standard. Před každým pull requestem, nejlépe před pushem do repozitáře, je dobré si spustit nette/code-checker, který nám zkontroluje všechny coding standardy.