Dokumentace formou příkladů

Peetee

Ahoj,

domnívám se, že zajímavý způsob jak se učit framework (/jakýkoliv jazyk) jsou ukázkové příklady a zdrojové kódy zkušenějších kolegů.

Stránka na Wiki:

https://blog.nette.org/

Můžete kouknout přímo tam, nebo se zde zapojit do diskuze i nadále nás zajímá Váš názor.

Cílem by mohlo být vytvořit sbírku příkladů, které zahrnou (velkou) část otázek typy „jak mám udělat …?“. Každý příklad by měl odpovídat na jednu takovou otázku a měl by být co nejmenší. Rozhodně netvrdím, že by tyto příklady měly nahradit dokumentaci, ale domnívám se, že by mohly z dokumentace převzít část tlaku (něco se bude složitě popisovat, ale na kód kouknu a vidím).

Psaní příkladů komunitou má několik zásadních vedlejších vlivů – především se domnívám, že pro programátory je přirozenější psát (a někdy i číst) kód než text. Zároveň napsat smysluplně stránku do dokumentace považuji za VELKÉ sousto, naopak napsat mikro příkládek může být otázka… chvilky.

S tím se pojí následující otázky:

co si obecně myslíte o výuce z zdrojáků?
byly byste ochotni napsat příklad?
máte nápady na témata, které je vhodná zpracovat? (bylo by vhodné vytvořit seznam)
napadá Vás způsob, jak zajistit, že do příkladů se nedostane něco co je špatně? (nějaký způsob prověřování kontrolování apod)

Budu moc rád za každý názor.

Editoval Peetee (24. 1. 2011 23:39)

Patrik Votoček

Jako nápad je to dobré a dokonce se s tím pokud vím do budoucna i počítá ale nejdříve je potřeba dokumentace jako taková aby se z těchto tutoriálů dalo odkazovat do dokumentace podrobnějším informacím.

Filip Procházka

Velice dobrý nápad, mě osobně se nejlépe učí ze zdrojáků, takže to vítám.

Jednou za týden napíšu příklad řešení nějakého jednoduchého úkolu (nebudu psát celé pluginy). Začnu tento týden a vyberu si nějaký jednoduchý úkol, asi začnu přepsáním https://forum.nette.org/…dnot-pri-mvc. V ideálním případě pod článkem proběhne diskuze a nějaký začátečník navrhne další téma. Když nebude odezva, tak si zase vyberu něco sám.

Jenom se nemůžu rozhodnout jestli si to psát na blog (který zeje prázdnotou) nebo krmit dokumentaci.

srigi

Kedysi som sa o nieco podobne snazil, ale nie vhodnou formou – kcel som zdielat cele aplikacie. Vrtak ma pravdu v tom, ze tutorial by mal byt podporeny dokumentaciou. Kazdopadne stale vidim, ze demand po tutorialoch je a asi sa tiez do toho pustim.

Peetee

Děkuju za názory. Osobně se psaní velice rád zúčastním (proto sem ostatně píšu).

Domnívám se, že je dobrý nápad zpracovat malé příklady, cílené spíše na začátečníky, kde budou psány ty nejelementárnější postupy, které jsou v Nette. Rozsahem a typem mám na mysli například:

jak zobrazit na každé stránce menu
jak zobrazit stránku pouze pro přihlášené (/pouze pro admina)
jak zaregistrovat a vytvořit vlastní helper
… (a spousty dalších)

Každý příklad je velice jednoduchý a vytvoření by nemělo trvat dlouho. A to je strašně důležitý! Všichni se tomuto projektu budou věnovat ve svém volném čase a není reálné, aby vytvoření jednoho bodu zabralo déle než… chvilku. Naopak čím méně, tím více příkladů je reálné dokončit, a s úspěšným dokončením roste chuť pustit se do dalšího. Proto navrhuji, aby se každý příklad skládal pouze z komentovaného zdrojáku (nějakého uzavřeného modulu nebo celé aplikace). Jaký na to máte názor?

Editoval Peetee (24. 1. 2011 16:06)

newPOPE

Ano je to dobry napad, hlavne ako tvrdi @hosipLan je dobra ta diskusia resp. nejaky „tutorial request“, nakolko je tu dost schopnych ludi tie problemy vyriesit behom … chvilky.

Problem vsak vidim v tom niecom ako zacal @srigi, ze aj ked nahodi celu app tak zaciatocnici budu mat trochu (viac ako trochu) problem porozumiet…

Nemam nejaky problem s malym helpom co sa tohoto tyka, ked budu nejake napady na co presne tie tut… pisat kludne nejaky dokopy dam.

Šaman

Nápad je to dobrý a dokonce si myslím, že by se to mohlo rozvíjet rychleji než dokumentace.
Asi každý kdo s Nette pracuje může sepsat takový best practise řešení nějakého problému. Dokonce mám sám na disku několik příkladů na holém skeletonu, když jsem něco testoval před nasazením do aplikace. Stačí je trochu uhladit, přidat nějaký průvodní textík nebo zhutnit komentáře a mohu to sem poslat.
Na dokumentaci jádra si netroufám, to by vyžadovalo důkladnou znalost zdrojáků Nette.

P.S. Tvůrci dokumentace by pak mohli mít trošku ušetřenou práci a to co oni popíší teoreticky, k tomu by stačil link na příklad z praxe.

Editoval Šaman (24. 1. 2011 16:26)

Filip Procházka

tak jsme společnými silami založili https://blog.nette.org/, můžete se do toho pustit :)

Dyštak bych poprosil Davida, aby nám tam nahrál „velký trojúhelník“ :) takhle to nevypadá nic moc :P

Editoval HosipLan (24. 1. 2011 20:43)

h4kuna

inspirace :D

Peetee

Super, sem rád že se věci hnuly.

To mě přivádí zpátky k mé otázce 4 – jakým způsobem docílit, aby příklady, zde založené, byly kvalitní? Především se domnívám, že i zkušený programátor může udělat chybu. Proto navrhuji vytvořit minimální kontrolní mechanizmus.

Myslím, že by bylo vhodné, kdyby každý publikovaný příklad prošel kontrolou někoho jiného, víc lidí víc ví a hlavně vidí. Super by bylo, kdyby u každého příkladu byla poznámka, zda ji někdo prošel.

Aurielle

Ono asi bude trošičku problém že každý člověk preferuje jiné metody/postupy, coding standart atd… proto řešení, které může být z pohledu jednoho člověka zcela správné, nemusí vyhovovat druhému člověku (předpokládej že to neovlivní funkčnost).

Peetee

gmvasek: ano, samozřejmě. Předpokládám, že když bude 100 lidí dělat stejný úkol vymyslí alespoň 101 řešení.

Ten, kdo by daný příklad kontroloval, by ho samozřejmě napsal jinak, ale přesto se domnívám, že lze posoudit správnost. O tom co je a co není správně by se tu dalo diskutovat. Můj nápad je takový, že kód musí být funkční a musí splňovat oficiální Coding standard, víc bych neřešil nebo bych nechal na diskuzi s autorem a korektorem.

Editoval Peetee (24. 1. 2011 23:30)

Šaman

Určitě by neuškodila diskuze pod každým příkladem a na základě připomínek by mohl autor příklad uhladit. Aby vzniklo skutečné Best Practise a ne jen asi to funguje..

Filip Procházka

Pro každou vytvořenou stránku přece není problém založit téma v sekci dokumentace, zde na fóru, kde by se prošli případné nesrovnalosti.

Co se týče coding standart, ten je jasně definován a měl by být v rámci dokumentace dodržován.

Peetee

Vytvořil jsem v dokumentaci novou stránku, kde by možná bylo vhodné shromažďovat nápady na další příklady. Nazval jsem ji Nápadník

Vycházím z myšlenky, že úvodní strana Kuchařky má jistou vážnost a přidat pouhou myšlenku, nápad, o kterém si třeba nejsem ani jistý, že je vhodné ji zpracovávat by byla škoda. Zároveň se domnívám, že by byla velká škoda o tyto myšlenky přijít.

Má představa je, že na úvodní straně budou pouze zpracované nebo rozpracované příklady. Zatímco v Nápadníku může být spousta, velká spousta nápadů na další příklady úvodní strana Kuchařky zůstane čistá. Přemýšlím nad tím tak, že by uživatel, který by se chtěl zapojit, si mohl procházet Nápadník, najít nějaké téma (které by ho samotného ani nenapadlo) a pustit se do něj – tím odpadne jeden (velice těžký) krok – vymyslet co budu dělat.

Ale přiznávám, možná je to blbost, nechávám na diskuzi.

Patrik Votoček

řekl bych že to zavání zanášením wiki. jednodušší to bude psát do nějakého vlákna. případně vždy založit vlákno pro danou stránku do kuchařky.

Ginny

Opravdu škoda, že se na to kašle.

Patrik Votoček

Na co se kašle? To jako musí pořád někdo něco někam psát? Když se ti zdá že se na to kašle zkus ti vyčlenit sám X hodin u dělat něco sám. (Není to tak jednoduché)

Filip Procházka

Mně tady hoří upomínka že jsem xdní v mínusu s těmi články :) Pořád to nejde a nejde, ale vidím to pozitivně tento týden :D

Editoval HosipLan (14. 2. 2011 7:42)

Ginny

Patrik Votoček napsal(a):

Na co se kašle? To jako musí pořád někdo něco někam psát? Když se ti zdá že se na to kašle zkus ti vyčlenit sám X hodin u dělat něco sám. (Není to tak jednoduché)

Pořád? Kdo kam něco pořád píše, můžeš mi prosím poslat odkaz?
Jednu dobu se tu řešilo (necelé 2 roky zpátky), že se rozjedou Nettecasty a kde jsou? Ještě, že je tu pár lidí, co jsou ochotní si ten čas najít a podělit se s ostatními.

Ano, problém mi to opravdu nedělá, sednout na to 2 večery (třeba i o víkendu) a něco vymyslet. Bohůžel se s Nette teprve pár týdnů seznamuji, takže není v mých silách něco napsat/natočit. A když už jsme u toho, kuchařka má být spíš ve stylu snippetů kódů s vysvětlením funkčosti (jestli jsem to správně pochopil) a tam by takový problém s časem přece neměl být – vytáhnu nějakou metodu z existujícího projektu, napíšu jak jsem to řešil + proč a je to.

A osobně preferuji neperfekcionistický způsob – tj. Lepší něco nedokonalého (co se dá časem vyladit) než nic (respektive něco, co je, ale musí to být dokonalé před vypuštěním do světa).

Editoval Ginny (14. 2. 2011 15:32)

mm-marek

ad prefekcionalistický přístup… když se něco dělá, má se to dělat pořádně. Pak vznikají „návody“ jako tohle , které rozhodně nevedou správným směrem výuky. To je Cimrmanovský přístup, průkopníků slepých uliček aneb „Přátelé, tudy ne“ :)

předpokládám že na tomhle právě pohoří většina pokusů – prostě když chceš někoho něco učit, nestačí tomu rozumět, používat, znát… na nějaké základní úrovni.

Editoval mm-marek (14. 2. 2011 15:51)

na1k

mm-marek, troufám si konstatovat, že to je ten klíčový problém s tvorbou dokumentace. Počet lidí zde na fóru schopných napsat kvalitní dokumentaci, která bude navíc čtivá a správně formulovaná, odhaduju na 10–15.

Tihle lidi pak něco napíší a pak se dohadují, co z toho je vlastně best practice. Proto nakonec došlo k nevyhnutelnému a dokumentaci píše David. On jediný stejně nejlíp ví, kterým směrem chce aby se fw vyvíjel, které konsturkce prosazovat a které naopak upozadit.

Proto vidím komunitní přínos k dokumentaci nanejvýš v reportování nedostatků, případně překladech.

Ginny

mm-marek napsal(a):

ad prefekcionalistický přístup… když se něco dělá, má se to dělat pořádně. Pak vznikají „návody“ jako tohle , které rozhodně nevedou správným směrem výuky. To je Cimrmanovský přístup, průkopníků slepých uliček aneb „Přátelé, tudy ne“ :)

předpokládám že na tomhle právě pohoří většina pokusů – prostě když chceš někoho něco učit, nestačí tomu rozumět, používat, znát… na nějaké základní úrovni.

Já jsem přece nenapsal, že základní úroveň stačí k učení druhých – to si nemyslím :-) Jenom říkám, že nejlepší cesta vpřed je hned začít – viz. Srigiho screencast = Natočil screencast, pár věcí se mu nelíbilo, tak ho později natočil znovu (ale hlavně dal k dispozici první verzi, která leč nebyla dokonalá, účel rozhodně plnila).

Filip Procházka

Ginny, jsou lidé, kterým činí opravdu velké problémy, najít si byť hodinku času. Můj případ. :-/ A nemysli si, že mě to neštve, ale prostě to nejde, až se budeš z práce vracet v 6 večer a dělat doma ještě na soukromých věcech, na které čekají další lidé, tak pak můžeš poučovat někoho o tom jak je to v pohodě najít si dvě hodinky času :) Tohle téma je bezpředmětné.

Prostě až bude čas, tak se to napíše.

Patrik Votoček

Ginny napsal(a):

Pořád? Kdo kam něco pořád píše, můžeš mi prosím poslat odkaz?
Jednu dobu se tu řešilo (necelé 2 roky zpátky), že se rozjedou Nettecasty a kde jsou?

Právě že nikdo asi jsi evidentně nepochopil co jsem napsal. Naopak jsem se ptal jestli musí pořád někde někdo něco psát? Aby se tu neobjevovali příspěvky jako ten na který jsem tím reagoval.

A osobně preferuji neperfekcionistický způsob – tj. Lepší něco nedokonalého (co se dá časem vyladit) než nic (respektive něco, co je, ale musí to být dokonalé před vypuštěním do světa).

Problém je že celé Nette je perfekcionalistické a snaží se tak vystupovat. Pokud budou k perfekcionalistickém software existovat odfláknuté návody řekl bych že to bude mít o hodně horší dopad než když nebudou existovat žádné.

Ginny napsal(a):

.. viz. Srigiho screencast = Natočil screencast, pár věcí se mu nelíbilo, tak ho později natočil znovu (ale hlavně dal k dispozici první verzi, která leč nebyla dokonalá, účel rozhodně plnila).

Ano srigi je přesně ten který si ten čas konečně našel. Uvidíme samy kdy si ho najde zase na další…

HosipLan napsal(a):

Ginny, jsou lidé, kterým činí opravdu velké problémy, najít si byť hodinku času. Můj případ. :-/ A nemysli si, že mě to neštve, ale prostě to nejde, až se budeš z práce vracet v 6 večer a dělat doma ještě na soukromých věcech, na které čekají další lidé, tak pak můžeš poučovat někoho o tom jak je to v pohodě najít si dvě hodinky času :) Tohle téma je bezpředmětné.

Nejde než souhlasit obzvláště pokud 80% dne trávíš prací, 10% přípravám přednášek (pár dní před přednáškou je to i 60%) a dalších 10% trávíš studiem novinek na internetu aby jsi o tom později mohl něco napsat…

Ad hodinka času je tomu cca půl roku co jsem sepsal https://doc.nette.org/…/smartobject a celkově odladění do stávajícího stavu zabralo min 5 hodin času (možná se ti to nezdá ale je to tak). Troufám si tvrdit že natočení 10min screencastu v dobré kvalitě sežere klidně 24hodin.

Filip Procházka

Dneska jsem napsal dva články umrčenci! Kdo bude další co? Kdo to hecne?