Restrukturalizace dokumentace

Je úžasné vidět, jak se svépomocí rodí dokumentace pro Nette. Už se dokonce uvažuje nad překladem do angličtiny a proto si říkám, že je nejvyšší čas dát dokumentaci rozumější strukturu a jednotný řád.

Struktura

V tuto chvíli je dokumentace koncipována jako přehled tříd s jejich popisem. V tom vidím velký nedostatek. Uživatel obvykle ví, co chce programovat, ale neví, jaké třídy k tomu má použít. Nejvíc se to projevuje u komplexnejších oblastí frameworku (např. Nette\Application), které je potřeba popisovat didakticky, vysvětlit logiku a filosofii, naopak přehled tříd a metod uživateli moc neřekne.

Dlouho jsem zvažoval, jakou strukturu upravit, a jako nejlepší se mi zdá následující.

1. Getting Started
2. The Definitive Guide
3. API Reference
4. Glossary & FAQ
5. Tutorials & Screencast & The Cookbook

1) Getting Started

Sekce pro vývojáře, kteří přišli k Nette poprvé. Bude je zajímat jak Nette stáhnout, nainstalovat, jakou má licenci a také jak vytvořit velmi jednoduchou aplikaci. Zde lze použít stručnou verzi současného Quickstartu. Klíčové je, aby se uživatel dokázal zorientovat a aby ho framework během prvních pár minut, které bude ochoten čtení věnovat, zaujal. Poté bude ochoten si jej stáhnout a vyzkoušet napsat první aplikaci – ale i tomu nevěnuje víc než 30 – 60 min času.

2) The Definitive Guide

Kompletní a vyčerpávající průvodce celým frameworkem. Koncipovaný tak, aby se četl jako kniha. Vzorem může být Definitive Guide to symfony http://www.symfony-project.org/book/1_2/.

Do něj bych zakomponoval převážnou většinu současné dokumentace, včetně Quickstartu. Přitom bych naboural dělení podle jednotlivých tříd. Metody a třídy zmíněné v dokumentaci by byly (zejména při prvním použití) proklikávací do API reference.

3) API Reference

Přehled všech tříd a metod generovaných z PHPDoc. Současnou podobu bych upravil, aby lépe zapadala do designu dokumentace a uživatel neměl pocit, že se dostal na zcela jiné stránky.

Nevýhodou je, že vylepšování této dokumentace je možné jen editací zdrojového kódu. Jak už jsem psal dříve, pokud má někdo zájem se na tomto podílet a dobře ovládá angličtinu, přístup do SVN mu poskytnu.

4) Glossary & FAQ

Slovníček pojmů a často kladené dotazy. Tohle asi nepotřebuje další komentář.

5) Tutorials & Screencast & The Cookbook

Sbírka návodů, postupů, tipů a triků. Jednalo by se o důležité rozšíření Průvodce, tj. alternativní „quickstarty“ (nejlépe včetně videoukázek), řešení specifických úkolů a vše, co se do Průvodce nevešlo.

Jednotný řád

Návod pro spoluautory dokumentace. Takový „coding standards for documentation“. Jasná pravidla, jak používat wiki-syntax, jakou formou psát, jak odkazovat, typografická pravidla.

Pro jednotlivé části dokumentace by měl existovat vlastní postranní panel. Přidal bych jednotný formát odkazování do API (např. ...odkaz vygeneruje metoda "link()":api:Nette\Application\Presenter::link, kde jako první parameter...).

Nejprve se pokusím navrhnout strukturu URL a převést současnou dokumentaci do nové formy (během té doby bych asi vypnul možnost editovat stránky). A samozřejmě, celé téma otevírám k diskusi, takže pokud máte nápady, sem s nimi!