Slovo úvodem – vize

Nejdříve chci Davidovi poděkovat za vlákýnko. Vzhledem ke špatnému stavu aktuální dokumentace k Nette jsme se rozhodli to začít aktivně řešit.

Vize je takováto:

aktuální dokumentace bude přepracována do 4 součástí:

• Nette – Quick Start (dále QS)
• Nette – The Definitive Guide (dále TDG)
• Nette – API Reference (dále API)
• Nette – Programmer's Reference Guide (dále PRG)

Nyní k jednotlivým částem detailněji:

Každá část dokumentace má svůj specifický účel, který musí plnit:

Quick Start

QS je první průvodce úplného začátečníka, také lákadlo pro ty, kteří nejsou ještě zcela rozhodnuti.

Měl by:

• Poskytnout čtenáři základní informace, návyky a postupy při vývoji
• Po jeho přečtení by čtenář měl umět vytvářet základní aplikace v Nette
• Jít přečíst rychle
• Být snadno pochopitelný
• Nenápadně by měl čtenáře seznámit s dobrými návyky vývoje v Nette – páč když se já, jako začátečník, začnu něco učit, tak jsem ze začátku rád za jakýkoliv způsob, aby mi to fungovalo. Neřeším co je „správně podle konvencí“ – ale když to první co začátečníka naučíme budou ty správné konvence, jsme vítězi…

Neměl by:

• Zahltit čtenáře detaily, které by neustál
• Být nepřehledný

The Definitive Guide

TDG By měl být dalším krokem jak nového začínajícího tak i pokročilého programátora v Nette.
Měl by poskytovat ucelený a kompletní obraz frameworku, všech jeho postupů, featurek atd. Jeho součástí by měly být příklady. Měl by být psán méně technickou formou a jeho cílem by mělo být to, aby čtenář práci s frameworkem bezezbytku pochopil. Měl by být rozčleněn na kapitoly a čtenáře postupně seznamovat se všemi postupy – od těch základních, po ty pokročilé.

Měl by:

• Být kompletní příručkou Nette Frameworku
• Obsahovat všechny potřebné informace, které potřebuje vývojář v Nette – začátečník i pokročilý.
• Čtenář by po jeho přečtení a porozumění probírané látce měl být schopen plnohodnotně vyvíjet v Nette bez potřeby jakékoli další dokumentace (ano máme ještě API a PRG, ale ty jen ulehčují hledání informací – nejsou a nemohou být náhradou TDG)…
• Obsahovat část duplicitních informací jako API a PRG – to je zcela v pořádku, všechny tři druhy dokumentace podávají část stejných informací, ale každý jinou formou.

Neměl by:

• Být složen jen z ukázek zdrojových kódů a pár řádků kolem
• Nahrazovat API, či PRG – je to jiný druh dokumentace

API Reference

Podobně jako např. u jazyka Java plní API roli jakési referenční příručky dovedené „at absurdum“. Když si programátor neví rady s konkrétní třídou, interface, či metodou – ve smyslu počtu a pořadí jejích argumentů, návratového typu, či rámcového popisu funkce, pomocí API může tyto informace rychle a efektivně najít. Taktéž bude možná v budoucnu možné integrací tohoto API do IDE rozšířit možnosti tohoto IDE např. o typovou kontrolu Nette kódu a další věci (to je aktuálně vzhledem k aktuálnímu stavu všech IDE pro PHP utopie, ale třeba někdy…).

Toto je jediná část dokumentace, kterou v podstatě již máme hotovou – díky tomu, že David pečlivě kód komentoval a díky tomu, že existují nástroje, jako je phpDocumentor. Jediné nad čím je třeba se zde zamyslet, je, zda do API neintegrovat ke každé třídě kde to má nějaký smysl příklad jejího použití – má to tak například JQuery – ale možná by bylo lepší toto mít až jako součást PRG…

Měla by:

• Poskytovat rychlou a efektivní cestu k získání určitého druhu informací

Neměla by:

• Poskytovat informace, které jsou poskytovány lepším způsobem jinými druhy dokumentace – například informace ve smyslu „jak na to“

Programmer's Reference Guide

PRG je poslední částí dokumentace – jedná se o jakýsi hybrid mezi API a TDG. Jeho poslání David dobře vyjádřil takto: „Pokud programátor víc že existuje třída Nette/String, ale neví jak ji přesně použít, pak se podívá do PRG“. Jinými slovy PRG neseznamuje čtenáře s tím, že něco existuje, nebo s tím že když chci vývíjet v Nette, musím vědět co je to to a to (přesně tohleto dělá QS a TDG). – PRG je rozdělen dle jednotlivých tříd a funkčních celků tak, že je možné nalézt jednotlivé části (vlastně tak ja kje rozdělena současná dokumentace k Nette). U každé části programátor najde, k čemu daná část je, jak se správně používá a příklad – a odkaz do API, či TDG. Taktéž tam najde Úplný popis toho co ta část umí – to v TDG být uvedeno musí také – ale tam to nemusí být na jednom místě (příklad: TDG je rozdělen na Začínáme, Pro pokročilé a Pro experty a ve všech třech částech povídá něco o Nette/Forms – tudíž je v TDG popis Nette/Forms rozdělen dle obtížnosti/detailnosti/whatever – v PRG oproti tomu je všechno o Nette/Forms hezky na jednom místě).

Měl by:

• Obsahovat všechny informace o všech popisovaných komponentách
• Umožňovat, aby čtenář našel co potřebuje a nezatěžovat ho informacemi, které ho v tu chvíli nezajímají
• Jednotlivé části by měly být unifikovaně rozděleny – ve smyslu, že popis všech komponent bude sestávat z nějakých částí – např.: Úvod, Účel, Popis, Kdy použít, Jak použít, Příklady, Schopnosti, …

Neměl by:

• Se snažit nahradit TDG – je to opět jiný druh dokumentace…

Tak to je takové stručné shrnutí několika předcházejících threadů. Udělám v doku vlákně vlákna pro jednotlivé druhy dokumentace a plán je takový, že v nich probereme, co komu v kterém druhu chybí, nebo co od něj očekává a potom se postupně pustíme do jejich vytváření…

Jinak budou platit dvě věci:

Nevím, jak je na tom v současnosti Nette se „stable“ a „dev“ (popř. s „nightly“) builds, ale kdyžtak bych to nějak vyspecifikoval. Každopádně bych zavedl to, že cokoliv bude součástí stable buildu Nette, BUDE NUTNĚ součástí dokumentace. A nikdy jinak.

Tím zavedeme pořádek.

No, toliko úvodem, jdu se najít a udělat ta vlákna…