Nette Documentation Preview

syntax
Psaní dokumentace
*****************

.[perex]
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 |https://www.lupa.cz/clanky/piseme-pro-web/]. Dokumentace je psaná v [Texy! |https://texy.info], 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 |https://www.deepl.com/translator] a ostatní vám váš text zkontrolují.
- V textu dokumentace spíše "mykáme" a jsme zdvořilí.
- V příkladech dodržujte [en:contributing/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 |https://github.com/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` a `en`: 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 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|https://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 |https://rogerdudler.github.io/git-guide/], nebo si pomoci některým z mnoha grafických nástrojů: [GIT - GUI clients |https://git-scm.com/downloads/guis].

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 |https://github.com/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.

{{priority: -1}}

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 a en: 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 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.