Co vylepšit na dokumentaci

Nejprve obecně. Dobrá dokumentace musí splňovat několik bodů:

• jít od jednoduchého ke složitému
• uvádět jen ty informace, které uživatel potřebuje vědět
• být pravdivá

Vím, zní to jako klišé, jenže právě v tomhle současná dokumentace selhává, a to především v částech, které jsou buď hodně staré, nebo vznikaly „komunitně“.

Dám příklad: první věta stránky o AJAXu zní: AJAXový požadavek lze detekovat metodou služby zapouzdřující HTTP požadavek $httpRequest->isAjax(). Ruku na srdce, komu to připadá perfektně srozumitelné? Ale hlavně: kdo jste kdy takto detekovali AJAXový požadavek? Tím jsou porušeny hned dva první body. Přičemž zajímavý fail je v tom, že nikde není zmínka o tom, jak AJAXové požadavky vytvářet.

Dále následuje kapitola Invalidace – ta krom úplně špatného názvu vysvětluje jakousi metodu isControlInvalid() – opět, kdo jste ji někdy použili? Teprve po této kapitole následují snippety. Má to být obráceně: uživatele zajímají především snippety, a teprve až se dozví o snippetech, mu řekneme, jak ho nechat překreslit.

Kapitola snippety začíná větou Nette je založeno na myšlence logických, nikoliv grafických prvků, – jak to souvisí se snippety? To je úplně zbytečný a tedy zavádějící obsah. (Aby bylo jasno, možná jsem tu větu napsal já sám, nechci se tímto postem někoho dotknout a vážím si práce všech, co do dokumentace přispěli.)

A tak dále. Když bych tedy měl říct, co je špatně na kapitole AJAX, tak přesto, že obsahuje fakticky správné a vyčerpávající informace, tak je vlastně špatně od začátku do konce. A to bohužel platí v určité míře pro řadu stránek.

Takže i úpravy jednotlivých stránek (nebo celků více stránek) by měl provádět jeden člověk, s respektem k výše uvedeným bodům. Popsat věc tak, aby uživatel hned věděl to podstatné, postupně se dostávat do hloubky a vyhnout se zbytečnostem.

A teď konkrétní vady:

Obecně

• na řadě míst se používají deprecated věci, to je třeba projít a odstranit
• všude, kde se hovoří o konfiguraci, je třeba uvádět konfiguraci pomocí config.neon
• na řadě míst (Session, Přihlašování, i zde neuvedených) je zmíněn DI kontejner, což je třeba odstranit

Formuláře

• úvodní text je hodně starý a začíná tím, jak tvořit samostatný formulář (Nette\Forms\Form). To dnes lidi nezajímá, takže spíš to chce začít tím, jak (třeba do sandbox) přidáme formulář (Nette\Application\UI\Form + onSuccess) a o samostatných formulářích se zmínit zvlášť
• to se týká i vykreslování formulářů, kde nemá smysl zmiňovat varianty bez Latte
• chybí tam 2.1 featury, jako je addCheckboxList, getHttpData apod.
• část „Validace celého formuláře“ je zcela zavádějící

Latte

• popis makra ifCurrent je nesmyslně v podmínkách, souvisí s odkazy

Konfigurace

• zmínky o DI kontejneru v úvodu jsou matoucí. Nejprve má přijít popis standardních parametrů config.neon. A teprve u sekce services zmínit kontejner
• sekce Prostředí je nadbytečná
• opět tam chybí 2.1 featury a přebývají deprecated věci (zejména factories)
• jako příklad vlastních služeb není dobré používat Database, protože to mate
• je nutno jasně uvést, jak službu dostanu do presenteru nebo jiného objektu. Klidně na to udělat samostatnou stránku. hotovo

Píšeme komponenty

• tady selhává výkladová stránka, text by měl popisovat tvorbu reálné komponenty včetně jejího použití v presenteru a nikoliv jen popisovat dílčí části (jako je šablona, odkazy) vytrženě z kontextu
• část „Komponenty do hloubky“ je příliš hutná, lepší je vysvětlit, že komponenty tvoří hierarchii jako DOM, nikoho nezajímá, že existuje nějaký interface IContainer apod.

Routování URL

• víceméně stačí odstranit deprecated věci jako práci s $containerem
• odstranil bych i sekci Masky, protože to je static hell a netřeba k tomu nikoho navádět
• Píšeme vlastní router je asi příliš stručné
• opět chybí nové features jako callback pro všechny parametry nebo proměnné s doménou

Přihlašování & oprávnění uživatelů

• opět bych odstranil použití kontejneru

Debugování a zpracování chyb

• tady by asi mělo být zmíněno zapínání přes $configurator a Tracy
• text obsahuje některé chyby, jako že E_NOTICE nebo E_WARNING se nezobrazují v Debug baru

AJAX & snippety

• vysvětlovat $httpRequest->isAjax() nebo isControlInvalid je docela zbytečné, stejně jako že „Nette je založeno na myšlence logických, nikoliv grafických prvků“, viz úvod

Databáze & ORM

• tohle je v české verzi strašná stránka, bylo by lépe nahradit strojovým překlad z anglické verze
• nicméně i anglická verze selhává v oněch primárních bodech. Začíná tím, jak vytvořit objekt Connection, ačkoliv jde o věc, kterou uživatel nikdy takto dělat nebude. To můžeme zmínit až někde na konci, když půjdeme do hloubky.

Sessions

• opět bych odstranil použití kontejneru
• konfigurace by měla popisovat config.neon, nikoliv API třídy Session

Odesílání e-mailů

• určitě bych téma nezačínal výstražným „Nikdy neposílejte e-mailem hesla ani jiné přístupové údaje.“, bez rady, jak to dělat jinak, je to nevhodný výkřik
• u použití šablon bych uvedl, že v nich nefunguje makro link (a třeba jak to obejít)

Cache

• opět problém s použitím kontejneru
• nezmiňoval bych templateCacheStorage

Lokalizace

• tady není zcela patrné, že Nette žádný výchozí překladač nemá

Testování

• tady chybí zmínka o Nette Testeru
• možná ten úvod lze zjednodušit, protože je použit v dokumentaci Testeru, ale určitě bych ho tam nechal

Stránkování

• tohle je docela malér, protože člověk se vlastně o stránkování moc nedozví. Tudíž je třeba téma přepsat jako ukázku, jak řešit stránkování přímo v presenteru, a pak se dostat k Paginator

Auto-loading tříd

• v textu není zmínka o Composeru
• zbytečný je i popis, jak vytvářet objekt RobotLoader, protože uživatel použije Configurator

Composer

• tady úplně chybí v úvodu nějaká motivace, proč Composer používat
• naopak s popisem instalace bych možná spíš odkázal přímo na web Composeru
• „Použití autoloaderu z Composeru“ je zastaralé

Jak se zapojit?

Na rovinu: dokumentace se sama nevylepší. Zkoušeli jsme to, ale skutečně se nevylepšila :-) Takže jsem moc rád za každého, kdo přiloží ruku k dílu. A jak na to: celá dokumentace je na Githubu https://github.com/nette/docs. Jak úpravy budou ve výsledku vypadat ukáže https://editor.nette.org. Změny tedy posílejte jako klasický pull request. Pokud si nejste jistí, můžete přijít s návrhem, nad kterým lze dále na Githubu diskutovat.

Jelikož máme anglickou a českou verzi, je potřeba je udržovat synchronizované, to znamená každá úprava by měla proběhnout v obou jazycích (může se prodiskutovat třeba v češtině a překlad udělat až finálně).

Zároveň taky oceníme korektury anglické verze. Ideálně celých stránek nebo alespoň kapitol.

A nakonec: můžete také pomoci vyřešit existující issues https://github.com/…/docs/issues