Co vylepšit na dokumentaci

před 4 lety

David Grudl
founder | 6705
+
+3
-

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

před 4 lety

David Matějka
Moderator | 5167
+
0
-

na řadě míst (Session, Přihlašování, i zde neuvedených) je zmíněn DI kontejner, což je třeba odstranit

Jo, je potreba smazat to ->getService(), ale musi se nekde zminit, jak se k te sluzbe dostat. Ze se jedna o Nette\Caching\IStorage, abys mohl vytvorit cache, ze se jedna o Nette\Mail\IMailer, abys mohl odeslat mail atd.

Jednotlive stranky dokumentace vice ci mene dobre popisuji, jak ktera sluzba funguje. Ale uz nemusis najit, jak to vlastne pouzit v aplikaci. Mozna bych pridal ke (vsem) strankam kapitolu „Jak pouzit xxx v aplikaci“ s kratkym prikladem, o jakou zavislost pozadat atd.

btw, pred par dny jsem udelal cheatsheet o di, mozna by se hodilo udelat neco podobnyho do dokumentace

Editoval matej21 (4. 3. 2014 20:17)

před 4 lety

David Grudl
founder | 6705
+
0
-

matej21 napsal(a):

…ale musi se nekde zminit, jak se k te sluzbe dostat.

Ano, to rozhodně. V tuto chvíli je to docela zastrčené tady https://doc.nette.org/…4/presenters#…, přičemž jde o dost zásadní informaci.

Cheatsheet vypadá suprově! Nechtěl bys připravit i EN verzi?

před 4 lety

mshot
Člen | 7
+
0
-

Že by svítalo na lepší časy? Já teď přepisuju jednu starší věc na aktuální verzi (tvořeno samozřejmě s pomocí nápovědy) a zjišťuju že nápověda moc nepomohla – spíš mám pocit že tak jak byla navedla lidi na špatné návyky :)

před 4 lety

Jan Tvrdík
Nette guru | 2535
+
0
-

Routování: odstranil bych sekci Masky, protože to je static hell a netřeba k tomu nikoho navádět

Nesouhlasím s odstraněním, někdo na to může narazit ve starší aplikaci a v dokumentaci by k tomu měl najít vysvětlení. Přidal jsem jenom varování

Routování: odstranit deprecated věci jako práci s $containerem

A čím to chceš nahradit? Přidáním RouterFactory zaregistrované v config.neonhttp://nette.merxes.cz/…routing.texy#…

před 4 lety

ic
Člen | 413
+
0
-

Teď mě tak napadlo… co tam do dokumentace ke každé stránce dát nějaký odkaz na editaci (dříve tam myslím byl).

Ať už přes oficiální, či neoficiální editor:
http://nette.merxes.cz/…routing.texy#…
https://github.com/…routing.texy