DOC10 aneb Nette Dokumentační Projekt „restart“
- Patrik Votoček
- Člen | 2221
Asi jste zaznamenali, že v poslední době je kolem dokumentace Nette celkem velký humbuk. V tomto postu se pokusím shrnout co se to vlastně děje a proč se to děje.
Než se pustím do samotného popisování co se to vlastně děje tak by se hodilo vysvětlit pár pojmů.
- NDP – Nette Dokumentační Projekt – Takto nazýváme všechno co se týká tvorby dokumentace. (Jinými slovy jedná se projekt tvorby dokumentace pro Nette Framework.)
- NDW – Nette Documentation Weekend – Je předem vyhlášený víkend kdy se sejdeme na jabberu/skypu/wave (online) nebo v hospodě (offline) a věnujeme se problematice tvorby dokumentace nebo ji tvoříme
- DOC10 – Dokumentace pro Nettte 1.0 – viz níže
- QS – Quick Start – Rychlý Start
Dnes je tomu měsíc a dva dny co proběhl jakýsi pokus o znovu rozběhnutí umírajícího NDP. Tím pokusem byl nakonec první (vlastně nultá) úspěšně realizovaný online NDW kdy jsme se sešli v asi 10ti lidech a zapomoci Google Wave jsme začali řešit nejrůznější problémy a aspekty dosavadního vývoje tvorby dokumentace. Shodou okolností se Ó veliký oddával dovolené a tak jsme si hezky ozkoušeli, že nemusí všechno dělat David ale se spoustou věcí mu můžeme pomoct. Jednou z nich je i tvorba dokumentace. A tak po první NDW jsem mohl s čistým svědomím říci: „Povedlo se! Jedeme dál!“.
Nedlouho po první NDW se začalo o dokumentaci hodně diskutovat. Z čehož nakonec vyplynulo uspořádání Skype konference kde jsme několik hodin diskutovali o tom jak znovu nakopnout umírající NDP. Po předchozích (nechci říct neúspěšných – protože kdyby jich nebylo nejsme tam kde jsme) pokusech jsme celkem věděli jak se to dělat nemá. Věděli jsme že nemá smysl se ptát celé komunity co a jak se má dělat jinak by to skončilo tak že by jsme se zase na ničem neshodli. Došli jsme tedy k tomu, že musíme jasně stanovit pravidla podle kterých se budeme řídit. Také jsme dospěli k názoru, že by se nám lépe tvořilo „na čistém stole“ a tak vzniklo něco čemu já pracovně říkám DOC10. Máme novou subdoménu s připravenou strukturou nové dokumentace. A také jsme jasně sepsali co a jak se má dělat.
Inu co dál? Dál nezbývá než se pustit do práce!
Tímto vás vyzývám pokud se chcete podílet na tvorbě nové dokumentace přečtěte si návod a zapojte se
PS: pokud jsi nováček v Nette a čteš tento post ozvi se budeme potřebovat „testery“ nové dokumentace. (děláme to přece pro vás!)
PSS: nová dokumentace je ve vývoji, je tedy vyřazena z indexování při hledání v googlu či jinde by jste na ní neměli narazit.
PSSS: já se du pustit do doplňování skeletonů o informace z NDW.
- David Grudl
- Nette Core | 8147
blacksun napsal(a):
Rád se zapojím jako rádoby samozvaný stylistický korektor a pravopisec.. Nejsem žádný přímo na toto študovaný odborník, ale hrubky mi málem vypichují oči, chybějící čárky se houpou ve vzduchu..
Takže bych mohl přispět tímto.
Super, to se hodí! Viď Vrtaku :-)
- Patrik Votoček
- Člen | 2221
David Grudl napsal(a):
Super, to se hodí! Viď Vrtaku :-)
Přesně tak!
@buff
Zatím česky. Budu raději za jednu kompletní dokumentaci než dvě rozpracované.
- iguana007
- Člen | 970
Majkl578 napsal(a):
Měli bysme v češtině (imho primárně) i v angličtině, ale na psaní anglické dokumentaci asi nemáme dost anglicky mluvících Nettistů. :) Zatím o nikom z NDP kdo by si na to troufl (kromě sebe) nevím.
Já bych mohl píchnout s tou anglickou verzí, sice moc času není, ale sem tam se nějaká ta chvilka po večerech najde ;)
- BigCharlie
- Člen | 283
S korekcí taky rád pomůžu, pokud nebudou „korigovaní“ příliš kvičet. Později snad i nějakou stránku přidám…
- odin
- Člen | 50
vrtak-cz napsal(a):
PS: pokud jsi nováček v Nette a čteš tento post ozvi se budeme potřebovat „testery“ nové dokumentace. (děláme to přece pro vás!)
V dokumentaci vcelku zasadne postradam prerekvizity a evidentne v nich
nemaji jasno ani autori stranek dokumentace. Neboli, vubec se nerozlisuje mezi
lidmi, kteri umi programovat (pripadne znaji nejaky jiny framework a lidmi,
kteri premysli jaky je rozdil mezi for a foreach)
Priklad:
https://doc.nette.org/cs/quickstart#…
Uvod je psany pro cloveka, ktery PHP framework vidi poprve:
Dalším krokem, který provedeme, bude vytvoření tzv. „presenteru“. To bude takový „ředitel“ naší aplikace. Než se do toho pustíme, je třeba si vyjasnit, co je to MVP:
vzapeti asi ale skonci na tom, ze nevi co je to navrhovy vzor. To je sice dal jaksi popsano, nicmene novacek, ktery chce zacit neco delat nepochybne teoreticky vyklad preskoci az na bod Implementujeme presenter. Kde pokracujeme tridou, abstraktni tridou a skeletonem, takze pokud ten clovek nic moc nevi o OOP tak je v tuto chvili definitivne ztracen. Coz nemusi byt nutne spatne – chci tim rict, ze by bylo fajn stanovit si (a to hlavne interne mezi autori dokumentace), kdo je cilova skupina:
- nekdo, kdo tusi neco o OOP?
- nekdo, kdo tusi neco o MVC?
- kdokoliv?
- nekdo, kdo pouziva jiny MVC framework?
- nekdo, kdo si doted smolil skripty v notepadu?
- Majkl578
- Moderator | 1364
odin napsal:
…
Cílem dokumentace není učit člověka programovat v OOP a už vůbec ne
učit ho programovat v obecném slova smyslu. Člověk, který chce používat
framework by měl mít nějaké znalosti (alespoň teoretické) o tom to OOP je
a jak v PHP funguje.
Dokumentace slouží jako zázemí pro člověka, který se chce naučit
s Nette Frameworkem – může to být začátečník v oblasti MVP, měl by
umět programovat v PHP a měl by mít alespoň základy OOP v PHP.
Navíc, opírat se o současnou dokumentaci (tj. subdoména
doc) není vhodné.
- 22
- Člen | 1478
Majkl578 napsal(a):
odin napsal:
…Cílem dokumentace není učit člověka programovat v OOP a už vůbec ne učit ho programovat v obecném slova smyslu. Člověk, který chce používat framework by měl mít nějaké znalosti (alespoň teoretické) o tom to OOP je a jak v PHP funguje.
Dokumentace slouží jako zázemí pro člověka, který se chce naučit s Nette Frameworkem – může to být začátečník v oblasti MVP, měl by umět programovat v PHP a měl by mít alespoň základy OOP v PHP.Navíc, opírat se o současnou dokumentaci (tj. subdoména
doc) není vhodné.
…u Zendu si tohle asi nemyslí! Takže buď by minimálně někde měly
být požadavky na člověka, kterej chce Nette používat a nebo spíš
opačně – zdroje, co se má člověk doučit nebo pochopit před tím, než
se do Nette vůbec pustí. PHP 101 od Zendu může být inspirací. Jinými slovy buď
uplatňovat přístup stylu: Nevíš, co je OOP, tak sem ani nelez, nebo: Neboj,
tady dokumentace je ještě lepší než od Zendu a všechno, co k Nette
potřebuješ se tady dozvíš, naučíš nebo ti dáme správné odkazy.
Takže podle mě by měla dokumentace obsahovat PHP manuál se zaměřením na
věci používané ve frameworku a samozřejmě PHP OOP tutoriál anebo se to
dá jednoduše vyřešit aspoň odkazy na http://www.linuxsoft.cz/php/ a http://programujte.com/?…
- Patrik Votoček
- Člen | 2221
22 napsal(a):
…u Zendu si tohle asi nemyslí!
Předně Nette není Zend…
Takže buď by minimálně někde měly být požadavky na člověka, kterej chce Nette používat a nebo spíš opačně – zdroje, co se má člověk doučit nebo pochopit před tím, než se do Nette vůbec pustí.
Tohle je přesně důvod proč chci oddělit tvorbu dokumentace jako takové od části pro začátečníky (Quick Start). V Quick Startu by určitě mělo být na začátku uvedeno jaké jsou potřebné znalosti (případně odkazy kde tyto znalisti získat). Naopak v dokumentaci samotné jsou tyto informace zbytečné.
Vlezu na stránku a nerozumím ani slovo… Něco je asi špatně. Musím se něco doučit. Tak začnu od začátku nebo hledám… (obecně ti na jakémkoli fóru nebudou chtít ukázat přesné řešení tvého problému ale budou se ti snažit dát indície aby se ti lépe hledalo – umět hledat je základ)
Takže podle mě by měla dokumentace obsahovat PHP manuál se zaměřením na věci používané ve frameworku
K čemu je pak manuál na stránkách php.net ?
a samozřejmě PHP OOP tutoriál anebo se to dá jednoduše vyřešit aspoň odkazy na http://www.linuxsoft.cz/php/ a http://programujte.com/?…
To je právě problém už nějáký čas se snažím (a né jenom já) najít použitelný tutoriál OOP programování v PHP na ten na programuje od Jakuba mrknu. Ale ten na linuxsoftu je nepoužitelný (zastaralí – PHP4)
- 22
- Člen | 1478
jen info: http://programujte.com/php/
jsem myslel jako zdroj učiva PHP, pro OOP pak tutorial z http://programujte.com/?….
Možná by bylo vůbec nejlepší napsat vlastní OOP tutorial přímo do Nette
dokumentace. Jako pěknej začátek cheatsheet od Martina
Ondřeje http://ondrej.mirtes.cz/…sheet-tahak/
- Vyki
- Člen | 388
Když jsem se OOP učil, tak jsem jako „tahák“ pužíval: George Schlossnagle – Pokročilé programování v PHP 5. Stejně když se to někdo bude chtít naučit tak si k tomu cestu najde, pořídí si knihu a stáhne pár příkladů. Nějaký krátký návod, kde by byly vysvětleny hlavní rysy OOP to ano, ale věnovat tomu velké úsilí je podle mého názoru ztracený čas.
- odin
- Člen | 50
Majkl578 napsal(a):
Cílem dokumentace není učit člověka programovat v OOP a už vůbec ne učit ho programovat v obecném slova smyslu. Člověk, který chce používat framework by měl mít nějaké znalosti (alespoň teoretické) o tom to OOP je a jak v PHP funguje.
Ale dost casto to tak nevypada. Kvetnate vypraveni se sice hezky cte, ale pokud se clovek potrebuje neco dozvedet, tak je to zrout casu.
Dokumentace slouží jako zázemí pro člověka, který se chce naučit s Nette Frameworkem – může to být začátečník v oblasti MVP, měl by umět programovat v PHP a měl by mít alespoň základy OOP v PHP.
Coz porad jeste muze zahrnovat nekolik velmi rozdilnych skupin lidi, viz predchozi post. Zejmena zacatecnik v oblasti MVP vs. znalec MVP, ale zacatecnik v Nette
Navíc, opírat se o současnou dokumentaci (tj. subdoména
doc) není vhodné.
Opiram se o to co vidim, protoze bych rad, aby se to usili venovane nove dokumentaci vyhlo starym osvedcenym chybam. Jde mi o to, aby se hlavne tvurci dokumentace jasne shodli na tom, pro koho co pisou.
- Cifro
- Člen | 245
vrtak-cz napsal(a):
Tohle je přesně důvod proč chci oddělit tvorbu dokumentace jako takové od části pro začátečníky (Quick Start).
Podľa mňa quick start nie je len pre začiatočníkov. S Nette môže chcieť robiť aj naskillovaný človek v PHP a iných frameworkoch, a quick start by mu mal ukazať že toto sa robí tak a tak v Nette.
Nemalo by platiť že quick start == pre začiatočníkov.
Editoval Cifro (15. 7. 2010 18:07)
- Patrik Votoček
- Člen | 2221
@Cifro „začátečník“ != „začátečník v PHP“…
Jenom abych doplnil co už jsem napsal o oddělení QS od zbytku dokumentace. Udělal bych to hlavně proto protože u QS je doopravdy nutné zaujmout a vytvořit ho hodně kvalitně. Troufám si tvrdit že vytvořit kvalitní QS zabere stejně dlouhou dobu jako zbytek dokumentace.
- Lopata
- Člen | 139
Podle mě je ale pravda, že mít vlastní Nette tutoriál o PHP by stálo za zvážení. Nějaké úvahy o tutoriálu tu už dokonce byly od Majkla578. Ochotným duším z fóra by se i snadněji odkazovalo a nikdo by si již nepletl své chabé znalosti OOP se špatnou Nette dokumentací.
// Možná bychom mohli i vytvořit návod zmanipulovaný, učit
jen věci typu foreach, class, … a neučit věci, co
za vás dělá Nette :-D
- Patrik Votoček
- Člen | 2221
Koukám že udělat korekturu webu není problém. :-D Teď ještě aby bylo co. Já se do toho hodlám zítra a o víkendu naplno opřít. Přidáte se někdo? A taky by se měl hodil někdo kdo by to po mě projel…
- David Grudl
- Nette Core | 8147
Technicka: asi by se hodila funkce „kopirovat stranku na novou URL“ aby se zachovavala historie, co?
- Patrik Votoček
- Člen | 2221
Jako že kopírovat ze staré DOC do DOC10? To by se využilo asi jenom u části TOOLS (Obrázky, Nette\String, Nette\Object…) nebo se pletu?
Btw jak to vypadá s TAGama?
- Patrik Votoček
- Člen | 2221
Jak tak koukám tak na to kolik lidí se tu hlásilo na korekci… tak se nic neděje…
- David Grudl
- Nette Core | 8147
Pokusím se tu stručně popsat Nette Roadmap pro potřeby dokumentátorů. Tedy nechci sepisovat všechny body, jde spíš o seznam, čemu se v dokumentování vyhnout, protože se to změní.
- omezení třídy Environment: záměrem je co nejvíce omezit používání
této třídy, v žádném příkladu by se proto neměla objevit.
V presenterech místo
Environment::getSession()neboEnvironment::getUser()prostě používejte$this->getSession()nebo$this->getUser(). - bude jiné nastavování development/production režimu
- změna formátu konfiguračních souborů z INI → NEON
- sumasumárum, Environment nemá smysl dokumentovat
- změny se budou týkat zadávání validačních pravidel u formulářů, veskrze ale nejde o nic, co by bránilo formuláře vysvětlit v současné podobě (s tím, že bych dokumentaci pak zaktualizoval)
- změny se dotknou snippetů, které zatím nedokumentujte
- stejně tak zatím nedokumentujte anotace
- změní se i interní mechanismus týkající se PresenterRequest + PresenterResponse, což nijak výrazně nebrání dokumentování Application, protože jde o interní mechanismy
- a nakonec je tu řada vlastností, které se ve frameworku objeví nově, případně drobných změn, které do dokumentace zanesu sám
- Patrik Votoček
- Člen | 2221
Tak jelikož nám nejede basecamp a nechceme se zdrzovat tak porosím než začnete upravovat nějákou stránku hoďte si nahoru:
DĚLÁM NA TOM "vrtak-cz":https://forum.nette.org/cs/profile/1639 .[caution]a uložte… pak teprve upravujte… aby 2 lidé nedělaly to samé…
- Richard Jedlička
- Člen | 51
Ahoj, diskuze okolo nové dokumentace nějak utichla. Znamená to projekt jaksi pomalu vyprchává ze světa, nebo na ní pilně pracujete? Pokud je pravda ta druhá možnost, v což doufám, jak jste na tom? Kolik už je hotovo, lze předběžně stanovit nějaké přibližné datum, kdy by mohla být hotova (nebo byste chtěli aby byla hotova)? Přeji hodně sil do dalšího tvoření.
Uiii
- Patrik Votoček
- Člen | 2221
Ahoj na dokumentaci se pilně pracuje. Diskuse utichla nejspíše proto protože není o čem diskutovat (vše je ujasněné a jenom se píše). Datum si z prstu nevycucám vzhledem k tomu že spousta klíčových věcí ještě není implementovaná (tudíž je nesmysl je dokumentovat) tak fakt nevím. Ale můžu slíbit že zároveň s vydáním Nette 2.0 k němu bude existovat i dokumentace.
- westrem
- Člen | 398
Neviem kam to napisat, tak to pisem sem. Mal by som taky mensi poziadavok na novu dokumentaciu, ktora sa rysuje.
Bolo by mozne vytvorit aj nejaku sekciu, v ktorej by sa sumarizovali vsetky mozne sluzby, ktore ide nastavit cez config.ini subor a ktore potom Nette interne vyuziva.
Neviem o nicom takom v sucasnosti a uprimne niekedy mi dost vadi, ze na to aby som vedel ako mam zaregistrovat napr autentifikator si musim kukat kod (toto je sice tak trochu blby pripad pretoze prave veci od autorizacie a autentifikacie su vcelu fajn zdokumentovane ale myslim to obecne).
Ja osobne sa v kode Nette uz celkom vyznam takze cca vzdy viem kde hladat ako Nette ktoru sluzby vola ale bolo by pekne mat nejaky sumar.
- bojovyletoun
- Člen | 667
Ahoj, jsem tu nový, nette pročítám týden a budu tvořit jeden projekt,. Hodně lezu do api/doc/doc10/příručka programátorů-.
- Patrik Votoček
- Člen | 2221
Ahoj, jsem tu starý, Nette pročítám víc jak rok a tvořím hodně projektů. Hodně lezu do api/doc/doc10/příručka programátorů a dalších.
- dasim
- Člen | 9
Zdravím,
pročetl jsem si to tu, ale není mi z toho jasné, jak jste na tom
s anglickou verzí. Zpracovává se nebo se čeká na dokončení české?
Pokud je poptávka, rád s překlady pohnu, jak jsem
nabízel.
- Patrik Votoček
- Člen | 2221
Czus DOC10 teď stála protože se na to všichni slušně řečeno ***… Ale ledy se začnou brzy hýbat…
- Bernard Williams
- Člen | 207
Nazdárek,
právě jsem dokončil korekturu (co se překlepů a drobných oprav týká) většiny stránek na https://doc.nette.org/. Problém je, že jsem tam našel spoustu stránek, které obsahovaly jen osnovu a teprve se plnohodnotně psát budou, takže jsem je nekontroloval..
V budoucnosti bych si mohl procházet i nově napsané stránky a právě na to se chci zeptat. Je nějaký jiný způsob, jak si tyto nové stránky (nově přidané texty) efektivně hlídat?
Bernard
- Jan Tvrdík
- Nette guru | 2595
Ano, je. Wiki – všechny stránky – RSS
https://nette.org/special/changes