Dokumentace – Dokumentační projekt

Takže, včera jsem se dostal konečně k přečtení Davidova článku o šablonách na zdrojáku a finálně a nezvratně jsem se rozhodl, že jdu do Nette a naplno.

Před několika dny jsem začal se studiem, pročetl všechnu doku, všechno postahoval, pročetl examply prozkoušel, pročetl toho fórum a tak nějak jsem Nette pochopil.

Ale:

1. zabralo mi to síleně moc času
2. byla to strašně neefektivní cesta učení se informací.

Prostě stav dokumentace pro Nette je takový, že skutečně žádná pořádná dokumentace není.

Dokumentace, která je na oficiálních stránkách, je už téměř zastaralá a neodráží aktuální stav Frameworku, nehledě na to, že dost podstatných věcí tam chybí (viz AJAX, a mnoho dalšího) – co se týče novinek, ty lze najít jen tady na fóru nebo některé věci až v examplech u stažitelných dister. Prostě všechny pokročilé techniky a věci – takové ty „killer features“ v doku nenajdu.

Což je stav, který nám nijak moc nepomůže v rozšíření Nette a také je to jeden ze zlých argumentů manažerů firem, proč místo Nette zvolit Zend.

Navíc už mě pekelně irituje, když spousta lidí o mém nejoblíbenějším PHP frameworku tvrdí, že není zdokumentovaný a že má špatnou dokumentaci – a bohužel je na tom něco pravdy.

Naprosto chápu, že dokumentace není, páč není snadné kvalitní doku vytvořit. David se plně věnuje dalšímu vývoji, školením a rozšiřování Nette, což je důležitější než dokumentace. Ale pokud chceme, aby se Nette opravdu masově rozšířilo, ujalo a bylo oblíbené, je dobré tu dokumentaci mít.

Tudíž bych si chtěl vzít tuto zodpovědnost osobně na svá bedra. – Samozřejmě bychom se na tom podíleli my všichni, jakákoliv pomoc je vítána – ale bude-li to nutné, jsem připraven provádět většinu prací s rebuildingem doku sám. A započít tak jakýsi Nette – Dokumentační projekt. Jeho cílem by bylo vytvoření kvalitní a plnohodnotné dokumentace k Nette – ne API a seznamu Davidových zápisků v blogu pospojovaných dohromady – ty zápisky jsou skvělé, ale dokumentace to není.

Samozřejmě že bychom vyšli ze stávajího materiálu, co máme k dispozici. A až bude projekt dokončen, chtěl bych, aby jeho výsledky byly tam, kde je současná dokumentace k Nette (neboli na stránkách Frameworku).

Do té doby bych chtěl poprosit (asi) Davida, nebo někoho kdo k tomu má oprávnění, zda by neudělal na hlavní stránce fóra kategorii Dokumentace, která by se stala středobodem našeho snažení.

Postup prací bych viděl tak, že bychom postupně refaktorovali stávající dokumentaci – quick start je celekm dobrý (možná ho prodloužit i o další featuresky), ale to ostatní zní příliš jako „příspěvky z blogu“, navíc jak jsem již řekl výše, není to úplné, spousta informací tam chybí a nebo to není napsáno tak, jak by dokumentace měla být.

Pracovali bychom postupně a ze současného stavu té která části by vznikla „pracovní verze“, kterou bychom uchovávali buďto tady na fóru, nebo někde jinde, má-li někdo nějaký nápad – třeba v SVNku formou .texy souborů? – Každopádně by se zpracovala vždy ona pracovní verze a předložila sem na fórum ke schválení, tady bychom se k ní všichni vyjádřili, opravili nedostatky, popřípadě provedli několik iterací tohoto procesu. A když by ten úsek byl schválený, mohl by ho David deploynout na stránky Nette Frameworku.

Jaký je na to váš názor a co si o tom myslíte?

Jestli s tím tedy souhlasíte, tak mi kdyžak udělejte pls ten thread (popř. navrhněte alternativní středobod projektu), a já se do toho hned pustím… V podstatě bychom mohli přes prázdniny hodně pokročit…

Popřípadě jestli máte někdo teďka aktuálně čas a ochotu, můžeme se do toho pustit ve více lidech…