Nette – Programmer's Reference Guide
- Inza
- Člen | 330
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…
Co si vy myslíte o Nette PRG? – Co byste doplnili/upravili/změnili na jeho aktuální podobě?
- kravčo
- Člen | 721
Myslím že PRG je jedna z prvých vecí, na ktorých sa môže okamžite začať pracovať, keďže jej podoba sa oproti terajšej dokumentácii veľmi nezmení, a zároveň verím, že jej obsah bude o triedu lepší.
Podľa mňa je jedným z problémov štruktúra:
Delenie podľa tried by bolo dobré poupraviť na delenie podľa funkčných
celkov – zmeny nebudú zásadné, niektoré veci (možno) spojiť, niektoré
rozdeliť. Mňa osobne irituje napr. desaťstranová dokumentácia
Nette\Application\Presenter, ktorá ma odradí hneď na začiatku.
Myslím, že je rozumné rozdeliť ju na menšie celky.
Hlavné témy by podľa mňa mali byť:
- Debug
- Environment & Config
- Forms
- Application (nabitá časť)
- Templates
- Caching
- Thread Safe Files
- Autoloading
- Authentication and User Rights
- Web Stuff (Nette\Web je taký mix kadečoho)
- Image Handling
Navyše nejaká dokumentácia čriev frameworku by si tiež zaslúžila odrážku:
- The Core (Object, Component, Collections, …)
Odkazy na konkrétny popis triedy/skupiny tried by mali byť duplicitné – tam kde tro má zmysel, čím by bolo ľahšie vyhľadanie, napríklad Application/Integrating Forms → Forms/Integrating in Applications.
- Honza Marek
- Člen | 1664
V zásadě souhlasim, ale názvy sekcí bych dával česky (nejsou to názvy tříd). Například Thread Safe Files podle mě zase není tak důležité, aby to zasloužilo hlavní sekci (hlavně, že cache se o to stará samo a data se ukládají do databáze). Naopak by byla určitě zajímavá sekce Ajax, protože o tom chce každý něco vědět.
- kravčo
- Člen | 721
Určite najprv vznikne česká verzia – samozrejme názvy budú česky, mal som pocit, že takto je jasnejšie, čo je ich obsahom… Ktoré sekcie to budú je samozrejme na diskusiu…
Ja si Nette\IO\SafeStream neviem predstaviť v nijakej inej
sekcii, preto som mu vytvoril samostatnú – opäť na diskusiu…
- Inza
- Člen | 330
Jo, zatím to vypadá dobře, mám k tomu pár připomínek a nápadů. Také jsem vymyslel z čeho by se jednotlivé části – resp. každá část PRG měla skládat, ale postnu to až zítra – je to na větší post a dneska mám šíleně věcí do školy co musím ještě poladit – ale jinak moc dík, že se to začíná hezky řešit;-)…
- David Grudl
- Nette Core | 8218
Troška kacířství – mrkněte, jak šikovně sloučili Programmer's Reference Guide & The Definitive Guide páni Railisté: http://guides.rubyonrails.org/
Zase jsem znejistěl, jestli skutečně potřebujeme tyto dvě dokumentace a nestačila by jedna. Navrhoval bych to ještě důkladně zvážit.
Také jejich API je inspirující http://api.rubyonrails.org/ – myslím to úvodní
povídání u tříd http://api.rubyonrails.org/…er/Base.html nebo příklady
u metod. Jen to chce vymyslet, jak dokumentaci generovat, přecejen podobné
věci do PHP souborů tahat nechci. Řešením by asi bylo propojení s webovou
wiki, třeba obsah https://nette.org/api/Nette/Object by se
zobrazoval na příslušené stránce na api.nette.org.
- Inza
- Člen | 330
Ad David:
Já bych se toho nebál. Na RoR doku jsme koukal a podle mě jsou dvě
dokumentace třeba – je skutečně plno věcí, které patří do jednoho
v tom druhém by být neměly…
Většinově je to z pohledu že v TDG bude uvedeno víc lidsky čitelné omáčky. PRG má být efektivní cesta.
Já jako programátor nechci aby mi v PRG bylo vysvětlováno, co a jak TDG se bude číst jednou (jako že si ho obvykle přečtu jen jednou). PRG budu používat jako referenční příručku… stále, opakovaně.
Já nemyslím že je dobrý nápad je spojit. Ochudíme se tím…
- Honza Marek
- Člen | 1664
Já bych to spojil. Když se to udělá dobře, tak to bude ideální. Ty dvě dokumentace se budou hodně překrývat a bude to těžké udržovat. Omáčky bude dost v tutoriálech jako quick start nebo ten na zdrojáku a třeba vzniknou i další (hello world za 5 minut).
- _Martin_
- Generous Backer | 679
Já mám takový pocit, že současná dokumentace je takový nepovedený mix TDG a PRG – místy je psán čtivě, formou článků (dobrým příkladem tohoto stylu psaní budiž Davidovy články na blogu – díky omáčce to člověk lépe chápe a je to zajímavější) a jinde je zase strohé popsání funkčnosti. A někde jsou i věci – dle mého – zcela zbytečné (použil někdy někdo z vás pojem Fully qualified action?). Nevýhodou těch čtivých článků je, pokud se rozhodnete něco hledat. Třeba takový signál presenteru: nejdřív se k němu musíte proklikat a potom se ještě pročítat textem, než najdete jeho použití. Asi to není nejlepší příklad, ale celkově: zrovna stránka věnovaná presenteru mě svou přeplněností odrazuje.
Sečteno a podtrženo: uvítal bych rozdělení.
- romansklenar
- Člen | 655
_Martin_ napsal(a):
Asi to není nejlepší příklad, ale celkově: zrovna stránka věnovaná presenteru mě svou přeplněností odrazuje.
Já vím, že psát čtivě neumím, proto jsem programátor, ne spisovatel
:)
Tehdy před půl rokem byla situalce jiná, presenter třeba nebyl
zdokumentován vůbec a nebylo od čeho se odrazit a pokud člověk neprošet
tucet vláken ve fóru, kde se všelijak různě probíraly problémy se
signály, persistentními parametry nebo s komponentama, tak se nehnul –
proto je to pokupě a psáno formou ledovce s přídavky kousků z fóra.
Taky se mi to nečte nejlíp, ale vím kde co hledat no :) s tím souvisí:
Sečteno a podtrženo: uvítal bych rozdělení.
Já taky, jak někde psal Honza, jQuery style je ideální:
- jednovětový popis k čemu co je
- popis parametrů a případně jejich hodnot
- kraťoučká ukázka použití, je-li to vhodné
Momentálně je to tak, že u těch upovídavějších dokumentací k třídám než bych něco našel, hledám odpověď radši v API nebo rovnou ve zdrojácích. Tím že je API hezky klikatelné je to i rychlé a pohodlné a přehledné, v IDEčkách to jde už samo… tím pocta Davidovi, že to dotáh do takové podoby ;) Nette je (podle mě) vážně příklad dobře a přiměřeně dokumentovaných zdrojáků a celkově zdrojáků jako vůbec ;)
Editoval romansklenar (15. 4. 2009 13:38)
- David Grudl
- Nette Core | 8218
romansklenar napsal(a):
Já vím, že psát čtivě neumím, proto jsem programátor, ne spisovatel :)
Vůbec si to neber osobně. Že jsi tu dokumentaci napsal je velká zásluha a minimálně splnila účel v tom, že (třeba díky ní) se k Nette dostal Inza a má vůli ji předělat. Ufff, přidám apel, byla by fakt škoda, aby se to někoho (a zcela oprávněně!) dotklo.
- romansklenar
- Člen | 655
:) hehe, to mě nenapadlo to tak myslet ;) pokud mi to dovolí čas rád bych se i účastil na dalším růstu dokumentace. Je fajn, že vzniká nějaký projekt, protože v jednom, dvou lidech se to nedá zvládnout, pokud se tomu nevěnuje člověk naplno. Jakmile přijdou nějaké povinnosti a musí to jít stranou tak je zle, protože Nette jde pořád dopředu a nestihá se to udržovat. Viz třeba prosinec & leden vs. zkoušky kde byl rekordní počet nových revizí, nových funkčností a nekompatibilit, které když se hned nepodchytily v dokumentaci a fórum se plnilo dotazy. Proto je důležité, aby se ta dokumentace udržovala aktuální i po tom co se napíše a čím více lidí bude na ní pracovat, tím větší šance je, že aktuální bude.
Vidím že, na další poslední sobotě bude zase co probírat ;)
PS: pokusím se dorazit.
Editoval romansklenar (15. 4. 2009 22:39)
- _Martin_
- Generous Backer | 679
romansklenar napsal(a):
Já vím, že psát čtivě neumím, proto jsem programátor, ne spisovatel :)
David Grudl napsal(a):
Vůbec si to neber osobně.
To se omlouvám, jestli to takhle vyznělo. Jen jsem to konstatoval a neměl jsem v úmyslu tím znevažovat práci, kterou jsi nad psaním dokumentace trávil. Jen si myslím, že když chceme předělávat dokumentaci, tak je v pořádku, řekneme-li, kde jsou jaké nedostatky (či naopak přednosti) a co jak upravit (aniž bychom za každou větou psali „přesto si velice ceníme práce, kterou pisatel dokumentace odvedl, atd…“ – to se rozumí samo sebou a tímto díky Davidovi za onen apel).
Teda, snad ty moje myšlenkový pochody pochopíte=D
- David Grudl
- Nette Core | 8218
Předpokládám, že to tak nikdo nemyslel ani nikdo nepochopil, ale je lepší si dopředu udělat jasno. S tím souvisí i druhá věc a to jsou autorská práva a licence k dokumentaci. Navrhoval bych použít stejný systém jako má Wikipedie. Co myslíte?
- Inza
- Člen | 330
Ještě k Davidově apelu:
Měl jsem to zmínit už v tom úvodním příspěvku omlouvám se. Tak tedy nyní.
**Chci moc a moc poděkovat všem, kteří se tvorby dokumentace již účastnili. Stejně jako těm, kteří se účastní diskuzí o ní – a plně souhlasím s Davidovým apelem.
Predevším díky vám přátelé – Vám, co jste už napsali nějaký ten řádek – bez ohledu na nějaké spisovatelské schopnosti – udělali jste co bylo třeba a když to bylo třeba – což je třeba víc než sem udělal já a to co jste udělali bylo velmi důležité a velmi to pomohlo. A člověk, který by tohleto kritizoval je idiot.
Vaší práce si velmi vážíme (já obzvlášťě a jsou mezi vámi i schopní talenti – to není jen odhad mám se spisovatelksou zkušeností již nějaké zkušenosti) a jen díky vám máme nyní z čeho vycházet.
Takže vám tímto chci (opožděně) velmi poděkovat. Veškerou činnost v rámci tohoto Nette – Dokumentačního projektu prosím vnímejte jako povýšení vámi velmi dobře udělané práce na vyšší úroveň. Budeme se snažit zachovat co největší část vašeho díla.
To co tu vlastně děláme není přepis dokumentace Nette, protože by byla špatná, ale vylepšení dosavadní (perfektní) dokumentace Nette, protože nám Nette dospívá a rostoucí komunita má větší nároky a my přeci chceme, aby byla dokumentace stále skvělá, ne?:-)…**
K té licenci:
David Grudl napsal(a):
Předpokládám, že to tak nikdo nemyslel ani nikdo nepochopil, ale je lepší si dopředu udělat jasno. S tím souvisí i druhá věc a to jsou autorská práva a licence k dokumentaci. Navrhoval bych použít stejný systém jako má Wikipedie. Co myslíte?
Ano je to dobrý nápad, prostě tím že člověk přispěje, se vzdává copyrightu ve prospěch Nette Foundation:-)…
- kravčo
- Člen | 721
Inza napsal(a):
Ano je to dobrý nápad, prostě tím že člověk přispěje, se vzdává copyrightu ve prospěch Nette Foundation:-)…
Podľa mňa je to inak – tým, že prispejem sa nevzdávam autorstva, ale dávam možnosť ostatným šíriť a upravovať dokumentáciu v medziach GFDL, avšak ten, kto šíri/upravuje musí rovnakú slobodu, akú dostal, poskytnúť i ostatným a musí rešpektovať autorstvo „diel“, ktoré šíri/upravuje.
- David Grudl
- Nette Core | 8218
Autorství se v ČR skutečně vzdát nedá a vůbec – vyžadovat jeho vzdání se mi připadá neetické.
- Inza
- Člen | 330
David Grudl napsal(a):
Autorství se v ČR skutečně vzdát nedá a vůbec – vyžadovat jeho vzdání se mi připadá neetické.
Ne, tak jsem to ani nemyslel, špatně jsem to formuloval:-) – Prostě i já si myslím, že použít to z wiki je dobrý nápad;-) – a to sem chtěl říct i tím prvním postem ale nějak jsem se do toho zamotal;-)…