Dokumentace co s ní dál, roadmap pro skype poslední neděli 27.12.2009
- mcmatak
- Člen | 504
Poslední sobota byla tentokrát virtuální a udála se hlavně na chatu nette, hlavním tématem bylo co s dokumentací. Pokračování se odsunulo na skype v neděli od 15.00. Aby z toho nebylo zase jen hádání o tom, že vše je naprd, že tramvaje jsou nebezpečné a že linux rulez a windows sucks, tak si myslím, že nejdůležitější je stanovit si nějaké body, problémy a potřeby, které řešit, vybrat ty nejdůležitější a najít nejrychlejší a nejméně problematické řešení!
Sepsal jsem tedy můj názor:
- dokumentace je neudržovaná, do dokumentace by měl mít možnost přispívat každý, pár vyvolených by mělo mít možnost schválit změnu v dokumentaci, pokud už se rozhodne někdo něco měnit, asi si myslí, že to má nastudované a opravdu našel chybu, problém nebo něco v čem bude tápat více lidí, i kdyby ta změna byla špatná vede to k tomu, že v dokumentaci něco chybí a příslušný admin to může řešit návratem k původní verzi a připsáním jedné věty: Může se zdát, že toto a toto je chyba, ale není to tak a je to správné řešení atd.!
- problém více verzí, nette se stále vyvíjí a co verze můžou se různé věci chovat jinak, od formulářů až po šablony, podle mne by každý článek duplikovatelný podle různé verze, nejdříve napíše někdo dokumentaci pro nette 0.9 bude se týkat zrovna Nette/Forms, až vyjde verze 0.9.2 tak se článek zduplikuje a upraví se v něm jen některé odstavečky případně se něco přidá, je to podle mne správný postup, protože nette 0.9 musí mít stále tu starou historickou dokumentaci se všemi chybami, které třeba řeší 0.9.2, tedy v důsledku by člověk měl mít někde přepínač na nette verzi, a u příslušného článku by se zobrazila jeho aktuální verze, nebo poznámka tato dokumentace byla napsána pro verzi 0.9, od té doby byly vydány další 4 verze, nebo by tam byla poznámka tato dokumentace byla přijata pro verzi 0.8, 0.9 atd.
- příklady, mnoho lidí se učí nejlépe z příkladů, a nebo jen z příkladů, navrhuji tipy, každý tip by byl článek, např. dokumentace pro Nette/Forms by měla odkaz na kategorii tipy pro Nette/Forms, tam by byly příklady, opět každý příklad by musel sledovat verzi nette, byl by za něj zoodpovědný autor, když už chceme zacházet do extrému s každou verzí nette by mohl autorovi přijít email: prosím uprav si tyto svoje příklady, zda jsou v aktuální verzi nette stále funkční, tipy by měli být něco jako: Jak na více stejných formulářů na stránce a samozřejmě část zdrojového kodu která řeší problém a také jaký problém je. Nebo jak na multijazyčné routy. Samozřejmě, by bylo vhodné, aby vždy příklad obsahoval vysvětlení pro co je vhodný, kdy se hodí, kdy to použijeme, co je základním problémem, co je workaround a co nette neumí řešit
- konkurenční přístup, pokud bude existovat jakýkoli jednoduchý wiki, problém bude, že někdo to vždy musí schvalovat, aby na web nešel blábol nebo aby dokonce někdo nesmazal dokumentaci, tedy příklad:
někdo upraví nette/forms, než to admin schválí, někdo jiný bude aktivní a upraví nette/forms jinak a teď co? co s tím? návrh byl řešit to githubem, kde by se texy kod článku verzoval a github umožňuje i administrátorská práva, cron by pak jednou za den mohl tyto verze článku stahovat někam do databáze článků webu (možnost jak teď hned umožnit pracovat ve více lidech na dokumentaci)
- mlady
- Člen | 24
Kenn napsal(a):
Já si hlavně myslím, že se o dokumentaci mluví už několik měsíců a skutek utek. To bych dal jako bod 0 :)
Ja si pamätám, že David písal, že dokumentácia je plánovaná na september 2009. Ak sa nemýlim, musel to potom odsunúť kvôli nejakej práci. Keďže každý musí z niečoho žiť, je pochopiteľné, že ziskové činnosti budú mať prednosť pred dokumentáciou. Možno by bolo riešením urobiť nejakú zbierku na dokončenie dokumentácie (ja som síce ešte v Nette dokopy nič nespravil ale verím tomuto projektu a 20€ by som bol schopný poslať).
Editoval mlady (29. 12. 2009 14:43)
- blacksun
- Člen | 177
Přispět na vývoj frameworku obecně či jen tak podpořit jeho tvůrce je samozřejmě možné, viz https://nette.org/cs/donate
- Ondřej Mirtes
- Člen | 1536
Ano, dokumentace umřela a bylo by potřeba ji hodně předělat, aby se zlepšila křivka učení :)
Já bych se zájmem rád pracoval na anglické verzi. Jen nevím, jestli mám otrocky překládat českou (která je navíc v dost žalostném stavu) nebo být inovativní a např. si vymyslet vlastní quick start (např. si vzít blog in 15 minutes od Romana Sklenáře, osekat ho a postupně ho ve quick startu vybudovat).
Pokud mi někdo tuto myšlenku posvětí, tak se do toho o zkouškovém klidně pustím :)
- Kenn
- Člen | 110
mlady napsal(a):
Ja si pamätám, že David písal, že dokumentácia je plánovaná na september 2009. Ak sa nemýlim, musel to potom odsunúť kvôli nejakej práci. Keďže každý musí z niečoho žiť, je pochopiteľné, že ziskové činnosti budú mať prednosť pred dokumentáciou. Možno by bolo riešením urobiť nejakú zbierku na dokončenie dokumentácie (ja som síce ešte v Nette dokopy nič nespravil ale verím tomuto projektu a 20€ by som bol schopný poslať).
Já to chápu, ale nikdo přece nechce, aby dokumentaci psal přímo David (i když upřímně, kdyby k tomu denně hodinu sedl a sepsal nějaké základy…). Důležitě se tady tvořily dokumentační skupiny a role (známé NDP že?) a skutek utek. Já sám bych rád přispěl, ale v Nette se taky zrovna necítím, obzvlášť v nových dev verzích, pro které především by se měla dokumentace začít pomalu psát.
Myslím, že se zde pohybuje docela dost lidí, kteří Nette znají jako své boty. Problém je, že nikdo nechce do dokumentace napsat. Proč by to taky dělali že? A i kdyby dostávali za dokumentaci zaplaceno, určitě by to nepřebilo programátorský plat.
- o5
- Člen | 416
Kenn napsal(a):
Myslím, že se zde pohybuje docela dost lidí, kteří Nette znají jako své boty. Problém je, že nikdo nechce do dokumentace napsat. Proč by to taky dělali že? A i kdyby dostávali za dokumentaci zaplaceno, určitě by to nepřebilo programátorský plat.
no tak tim to rozhodne nebude!
jestli nekomu neni neco jasne, tak ma API ne? :D
- mlady
- Člen | 24
blacksun napsal(a):
Přispět na vývoj frameworku obecně či jen tak podpořit jeho tvůrce je samozřejmě možné, viz https://nette.org/cs/donate
O tejto možnosti samozrejme viem. Je však rozdiel prispieť x CZK na podporu tvorcov a zozbierať nejaku sumu s konkrétnymi požiadavkami.
- Jakub Šulák
- Člen | 222
ono se také samozřejmě dá uvažovat o nějakém zvýhodnění těch, kteří přispějí na dokumentaci. Tak se dá celkem snadno přinutit lidi k platbě.
- Honza Marek
- Člen | 1664
Kenn napsal(a):
Myslím, že se zde pohybuje docela dost lidí, kteří Nette znají jako své boty. Problém je, že nikdo nechce do dokumentace napsat. Proč by to taky dělali že? A i kdyby dostávali za dokumentaci zaplaceno, určitě by to nepřebilo programátorský plat.
Hlavní problém je ten, že není známá požadovaná struktura té dokumentace. Kdyby tohle bylo, tak já bych sem tam něco sepsal. Určitě i jiní.
- Kenn
- Člen | 110
Honza Marek napsal(a):
Hlavní problém je ten, že není známá požadovaná struktura té dokumentace. Kdyby tohle bylo, tak já bych sem tam něco sepsal. Určitě i jiní.
Hlavní problém je, že se o dokumentaci pořád mluví a nic se neděje :) kde je Inza, který sliboval, jak se do dokumentace pustí, pak že se do ní teda pustí až bude nová verze a skutek utek.
Struktura by byla dobrý základ. Určitě by nebylo marné to (pořádně a s nějakým výsledkem) prodiskutovat s Davidem, domluvit se, jestli teda psát dokumentaci pro verzi 0.9 nebo pro dev verzi a budoucí 1.0 nebo pro obě verze, protože kdo ví, kdy 1.0 vyjde že. Jeden spolehlivý a znalý člověk by byl pověřen vytvořením základní kostry dokumentace a třeba vytvořením stránek, které je potřeba zaplnit a stránky by pak mohli plnit ostatní podle svých vědomostí.
Spoustu věcí do dokumentace by určitě mohl napsat každý, kdo s Nette aspoň chvilku dělá, ale pro začátečníka jsou i tyto jednoduché věci složité na pochopení, hlavně bez nějakých funkčních příkladů (viva la Romanův Blog v Nette). Pochybuju, že Quick start bude na verzi 0.9 bez úprav fungovat.
- Ondřej Mirtes
- Člen | 1536
Podle mě by dokumentace měla být stavěná tak, aby tam každý problém byl uveden v kontextu, čeho se týká. Abych u formulářů našel zmínku o nutnosti přesměrovávání a flashMessage, abych tam našel, jak má vypadat metoda pro zpracování odeslaného formuláře, abych tam našel továrničky.
Abych u Laděnky našel, jak se zbavit bílé stránky a jak si Laděnku zapnout na serveru.
Abych u přihlašování našel best practice pro přesměrování na stránku, ze které uživatel na přihlašovací formulář přišel.
Aby u šablon byl do detailů vysvětlen {block} a {extends} systém…
Dotazy na fóru se točí furt okolo toho samého a bylo by fajn odpovídat formou odkazů do dokumentace.
Jak to teď vypadá s wiki? Jde vše editovat? Fakt bychom s editací textů neměli váhat a neměli bychom se bát (změny jdou vracet a jde snadno zjistit, co kdo měnil) – Nette je skvělý framework, ale dokumentace snad v horším stavu, než je teď, ještě nebyla.
- Jakub Šulák
- Člen | 222
Pohla se někam diskuze o dokumentaci?
Trochu mi přijde, že se tu neustále diskutuje nad tím, jak to bude
nejlepší…ale nic dál.
Osobně mě příliš nezajímají věci jako Quick Start, apod., které jsou
dost složité na přípravu. Zato chybí aktualizovaný průvodce
programátora. Přikláněl bych se proto k dočasnému-trvalému
řešení:
Udělat na webu možnost psát dokumentaci pro jednotlivé main verze (možnost
přepínání mezi nimi).
První dokumentace by byla pro unstable verzi (budoucí verzi 1.0). Rozvržení
jak to udělat je asi tisíc. Osobně bych to viděl na rozvržení základních
kategorií (Bezpečnost aplikace, Routování, Komponenty, Tvorba vlastních
komponent) a pod nimi jednotlivé podkategorie – články.
Pod každým článkem by pak měla být možnost vkládat příspěvky (příklady), jako na php.net.
Vytvořit takovouto strukturu nám při diskuzi nedá tolik práce a jak bude vytvořena struktura, můžeme psát dokumentaci.
Psaní dokumentace bych dělal metodou „pisatel – korektor“. Každý kdo chce psát dokumentaci by požádal o povolení (nebo to mohou být i lidé co mají x příspěvků ve fóru). Po provedení změny v dokumentaci by změna čekala na schválení jiným člověkem s tímto oprávněním.
Jde o to, zda nějaká Wiki aplikace toto umožňuje, nemám zkušenost.
- Jakub Šulák
- Člen | 222
Ačkoliv si nesmírně vážím Davidovi práce, myslím si, že by měl
v tomto případě změnit priority, nebo systém řízení projektu.
Tedy:
- neimplementovat nové funkce do frameworku, jelikož se stávají nepoužitelnými, pokud k nim není dokumentace a věnovat se systému stránek, tak aby komunita byla schopna vytvořit dokumentaci
- předat vývoj webu komunitě (respektive konkrétním lidem), kteří jsou ochotni a schopni web předělat
Chápu, že toho má David hodně, ale ta dokumentace je od začátku to, co sráží (zbytečně) Nette do kolen. A čím je Nette dokonalejší, tím víc je cítit chybějící dokumentace.
- Ani
- Člen | 226
Já teda nevím, ale základy se člověk naučí i z toho co je tam teď a pak stačí sledovat Changelog…
Nějak mi uniká důvod proč to tak moc dramatizujete. Navíc se tu pořád řeší nějaký sytém práv, no nevím, když by někdo v současný wiki, vytvořil, těch pár stránek, které chybí, tak je časem lidi doplní a bude dokumentace hotová.
Když by se tolik energie jako se dává do plánovaní, věnovalo tvorbě… ;-)
Ale nakonec já tam toho moc psát nebudu, tak maximálně opravím nějakou chybu jako doteď, tak je to vlastně Váš projekt. :-)
- Jan Tvrdík
- Nette guru | 2595
Jakub Šulák napsal(a):
- neimplementovat nové funkce do frameworku, jelikož se stávají nepoužitelnými, pokud k nim není dokumentace a věnovat se systému stránek, tak aby komunita byla schopna vytvořit dokumentaci
Zde jsem si dovolím nesouhlasit. Vývoj FW musí běžet dál a nové funkce jsou použitélné i bez dokumentace (stačí poctivě sledovat všechny commity).
- předat vývoj webu komunitě (respektive konkrétním lidem), kteří jsou ochotni a schopni web předělat
Tohle bych viděl asi jako ideální řešení.
V současnosti se AFAIK čeká na dvě základní věci:
- Až mi David pošle (nebo někde uveřejní) návrh nové dokumentace (vypracovaný už před mnoha měsíci).
- Až David opraví kritické bugy wiki (nevím, zda tohle je, či není hotovo) + případně spustí alespoň ty tagy.
- Jakub Šulák
- Člen | 222
Sledování changelogu podle mého nestačí, spousta best practice vzniká i v jiných fórech (a asi také na Poslední sobotě). A pokud mají všichni využívat naplno Nette, tak bez dokumentace to nepůjde.
Co se týče energie věnované plánování – naprostý souhlas – proto jsem se ptal, jak to vypadá s technickými prostředky k tomu, aby se nápověda začala psát. Tak aby se skutečně udělala nějaká road-map a jelo se.
- David Grudl
- Nette Core | 8158
Finalizoval jsem rozcestníkovou stránku dokumentace a přidal pro tvůrce obsahu seznam všech stránek.
- pekelnik
- Člen | 462
David Grudl napsal(a):
Finalizoval jsem rozcestníkovou stránku dokumentace a přidal pro tvůrce obsahu seznam všech stránek.
Je tedy nyní možné dokumentaci upravovat? Mohl bych také dostat přístup? Jak to bude s asi klíčovou otázkou verzování dokumentace (nemyslím wiki verzování) podle Nette?
PS: Ještě bych měl drobné výhrady k členění stránky Průvodce programátora.
- Slovníček a Rychlý přehled pojmů jsou zastrčené pod Nette\Application.
- Ze stránky Průvodce programátora bych odstranil celý levý sloupec vyjma Quick startu. Imho jsou to povětšinou odkazy na jiné stránky z hlavního rozcestníku Dokumentace. Naopak celý prostor bych věnoval pravému sloupci, tedy skutečnému průvodci.
- Nadpis Class reference je zbytečný a zavádějící neboť se jedná o kapitoly probírající komplexní témata a ne jedntlivé třídy (jako tomu bylo v začátcích dokumentace)
No a ještě jeden návrh – ano, mohu si ho strčit za klobouk :)
HOWGH
- hurvajs
- Člen | 86
mcmatak napsal(a):
1. dokumentace je neudržovaná
Presne jeden z duvodu, proc jsem Nette opustil a v podstate na nej zanevrel. Mozna mel nechat p. Grudl cely projekt nepristupny (odhadem nekolik let) a zpristupnit ho tehdy, az kompletni dokumentace a ne tohle, co se tvari jako „radoby“ dokumentace. To ze neni, nebo je zavadejici je hodne spatne. Podle me nema Nette sanci na uspech. Muze byt sebedokonalejsi, sebekrasnejsi, neskutecne cisty kod, ale bez dokumentace je projekt ztracen. A to ze p. Grudl slibuje, je sice krasne, ale prd platne. Ohledne dokumentace jsou stale jen reci, ale skutek utek… Bohuzel musim uvest, ze prechod na Nette byl jeden z velkych omylu, kterych jsem se dopustil… Ted uz jen musim jeden projekt dokoncit, pak jej uzavru a budu pokracovat v poradnem frameworku s kvalitni dokumentaci.
Editoval hurvajs (13. 1. 2010 14:42)
- David Grudl
- Nette Core | 8158
- stránka Poslední změny přehlednější a má RSS výstup
- sepsal jsem podrobnější popis syntaxe, včetně zápisu meta informací
- Dokumentace by se měla blížit do finální podoby, lehce upravená Příručka programátora
- engine je z 90 % dokončený a neměl by mít chyby
Hlavní téma bych teď upnul k návrhu URL struktury a rozdělení stránek mezi guides.nette.org, wiki.nette.org, nette.org a případně další subdomény, byla by-li potřeba.
Dokud nebude konsensus ohledně struktury, nevytvářejte prosím anglické stránky, nemá ani moc smysl opravovat chybné odkazy.
- Jan Tvrdík
- Nette guru | 2595
Začal bych zvěřejněním návrhu struktury z Poslední soboty a pak by se to připomínkovalo. Nebo máš jinou představu?
- Jan Tvrdík
- Nette guru | 2595
Je bordel v URL:
https://nette.org/cs/Referencevs.https://nette.org/cs/referencehttps://nette.org/cs/Proč%20zvolit%20Nette%20Framework?vs.https://nette.org/cs/proc-zvolit-nette-framework
Asi se rozbil filter na psaní URL pomocí hranatých závorek.
- Jan Tvrdík
- Nette guru | 2595
@David: Můžu zveřejnit návrh struktury dokumentace nebo ještě na něco čekáme?
- David Grudl
- Nette Core | 8158
Ajó, já jsem myslel, že mluvíš o návrhu z Google Wave. Tohle se dokumentace jakožto programátorské dokumentace týká velmi okrajově, respektive nepřináší nic, co by už na webu nebylo. Takže já to asi zase smažu, ok?
- Jan Tvrdík
- Nette guru | 2595
Tak jsem to zase smazal :) Zítra nebo úplně jindy dám na web informace z Google Wave.
- David Grudl
- Nette Core | 8158
Web https://nette.org je víceméně hotový. Takže co dál. Nejdřív bych chtěl zrealizovat:
- zautomatizované vkládání pluginů na addons.nette.org
- komentáře přímo pod články (opustilo by se propojení s forum.nette.org)
A nejvyšší čas začít pracovat na wiki.nette.org a guides.nette.org. Trocha inspirace
- Ondřej Mirtes
- Člen | 1536
Jakým způsobem se bude tedy řešit verzování dokumentace – pro 0.8, 0.9 a 1.0?
- _Martin_
- Generous Backer | 679
Ondřej Mirtes napsal(a):
Jakým způsobem se bude tedy řešit verzování dokumentace – pro 0.8, 0.9 a 1.0?
Jen poznámku, která s tím trochu souvisí: bylo by dobré někde vést změny mezi jednotlivými stable verzemi – a tím nemyslím hodně vláken ve fóru, ale nějaký seznam pro každou verzi, aby se stačilo podívat na jedno místo a bylo hned jasné, co dodělat do dokumentace. A klidně by v tom seznamu mohla být každá položka prokliknutelná k vláknům, kde se ta fičurka řešila.
- Ondřej Mirtes
- Člen | 1536
_Martin_ napsal(a):
Jen poznámku, která s tím trochu souvisí: bylo by dobré někde vést změny mezi jednotlivými stable verzemi – a tím nemyslím hodně vláken ve fóru, ale nějaký seznam pro každou verzi, aby se stačilo podívat na jedno místo a bylo hned jasné, co dodělat do dokumentace. A klidně by v tom seznamu mohla být každá položka prokliknutelná k vláknům, kde se ta fičurka řešila.
Tohle podle mě splňují vlákna k vydání jednotlivých stable verzí v changelogu:
- https://forum.nette.org/…on-verze-0-9
- https://forum.nette.org/…-verze-0-9-1
- https://forum.nette.org/…-verze-0-9-2
Ale bylo by fajn mít přesnější návody – setkal jsem se s případem, kdy si člověk nedokázal poradit s odstraněním environment variables jako %modelsDir% apod…
- _Martin_
- Generous Backer | 679
Ondřej Mirtes napsal(a):
Tohle podle mě splňují vlákna k vydání jednotlivých stable verzí v changelogu
Vida, tohle jsem mezi těmi všemi vlákny přehlédl. A jsou tam opravdu všechny změny? Možná by nebylo špatné to vést přímo jako stránku. A ty odkazy by mohly být nejen na oficiální uvedení novinky, ale i na všechny důležitá témata s tím spojená (což by si žádalo jistou důslednost). Něco jako:
- Nové formuláře, více na [1], [2] a [3]
- Jan Tvrdík
- Nette guru | 2595
Nejprve OT: Oranžové odkazy v patičce by mohly mít při hoveru oranžové pozadí a ne modré. Mám dojem, že to tak i kdysi bylo.
Těším se na komentáře přímo pod články. Budou vidět přímo (jako třeba na php.net) nebo se k ním budu muset prokliknout přes wiki menu, jako je tomu nyní? U některých stránek mi přijde dobré zobrazit komentáře rovnou, u jiných je zase lepší se komentáři nenechat rušit.
Existuje nějaký návrh rozložení vlastní dokumentace (guides)? Bude po třídách (např. Nette\Application\AppForm)? Budou tématické celky (např. Formuláře, Práce s HTTP hlavičkami)? Bude to kombinované?
Jsem také názoru, že verzování dokumentace vůči stable verzím Nette je třeba řešit.
Changelog by měl být přesunut z fóra na https://nette.org/. Mám dojem, že to bylo zmiňováno i na Poslední sobotě (ano, zase Džínová – tam se toho fakt probralo hodně :)
- PetrP
- Člen | 587
Jan Tvrdík napsal(a):
Těším se na komentáře přímo pod články. Budou vidět přímo (jako třeba na php.net) nebo se k ním budu muset prokliknout přes wiki menu, jako je tomu nyní? U některých stránek mi přijde dobré zobrazit komentáře rovnou, u jiných je zase lepší se komentáři nenechat rušit.
Trochu se bojím kolik míst člověk bude muset kontrolovat: commity, rss fóra, rss změn dokumentace, rss komentaru u dokumentace…
Mimochodem když už píšu o rss změn dokumentace, nemohl by si davide do textu dát diff té změny, aby to nemusel rozklikávat v čtečce a rovnou vyděl?
- Jan Tvrdík
- Nette guru | 2595
Zkusil jsem si přidat do user CSS
#page {margin: 0 auto !important;}. Uvidím, jak si zvyknu.
- Inza
- Člen | 330
Aha, peklíčko!
Davídku, potřebujeme todolist! – Klidně to napiš třeba sem do fóra, ale napiš to! A ne že na to budeme zase čekat půl roku!
Když nám dáš todolist, začneme vyrábět doku:-) – jinak já jsem si už prošel novou strukturu webu, opravil jsem pár typo a místy navrhnul pár změn, ale bez todolistu toho víc nezmohu! Tak už se na něj těším:-)
Jinak nový web je velmi nice! Velké díky patří všem, co se na tom podíleli!:-)