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.