Dokumentace seřazená abecedně

Upozornění: Tohle vlákno je hodně staré a informace nemusí být platné pro současné Nette.
Grelek
Člen | 233
+
0
-

Zdravím,

nevím jak vám, ale mně občas vadí, že dokumentace není seřazená abecedně. Kolikrát koukám na místo, kde by teoreticky mělo být třeba Formuláře a ono tam je Databáze & ORM.

Je to spíš takový detail, ale myslím, že by to „usnadnilo“ hledání mnoha dalším.

hrach
Člen | 1834
+
0
-

Souhlas. Ja se tam taky stale nemuzu vyznat.

Patrik Votoček
Člen | 2221
+
0
-

Dokumentace by měla aktuálně být seřazena tak jak by to dává logicky smysl a jako by se měl postupně nette učit nováček.

vvoody
Člen | 910
+
0
-

No je to pekná myšlienka a celkom ju chápem ale keď som s nete začínal tak som s tým hľadaní mal tiež problém až som sa v podstate naučil naspäť cca pozíciu jednotlivých odkazov.

Grelek
Člen | 233
+
0
-

Patrik Votoček napsal(a):

Dokumentace by měla aktuálně být seřazena tak jak by to dává logicky smysl a jako by se měl postupně nette učit nováček.

Nebo alespoň tam přidat možnost řazení, třeba logické a abecední.

hrach
Člen | 1834
+
0
-

Je to uplne nahovno. K tomu je quickstart. Dokumentaci se nikdo neuci tak, ze jeden den sedne a projde to vsechno podle doporuceneho poradi. Projde quickstart a pak experimentuje… a to uz potrebuje hledat… ne procitat..

22
Člen | 1478
+
0
-

Mně by úplně stačilo, kdyb se zrušil ten hover efekt nad metodami v API, a fungovalo to na click, takhle mi API poskakuje, a kolikrát zjistím, že jsem kliknul na jinou metodu, než jsem měl původně v úmyslu…

Editoval 22 (30. 8. 2012 23:32)

hrach
Člen | 1834
+
0
-

To uz je zrusene, ne? :)

22
Člen | 1478
+
0
-

Jo, fakt :-) dobré…

paranoiq
Člen | 392
+
0
-

Patrik Votoček napsal(a):

Dokumentace by měla aktuálně být seřazena tak jak by to dává logicky smysl a jako by se měl postupně nette učit nováček.

hrach má pravdu. k tomu je quickstart. navíc pořadí témat v quickstartu a v příručce teď není úplně stejné

Caine
Člen | 216
+
0
-

Souhlas + bych přejmenoval „Zpracování obrázků“ na jen „Obrázky“ a „Odesílání emailů“ na jen „Emaily“, když totiž po delší době něco hledám, hledám jen ten výraz (emaily, obrázky).

vvoody
Člen | 910
+
0
-

@Caine: +1 presne toto :D

pekelnik
Člen | 462
+
0
-

Souhlas. Prejmenovat „Prace s necim“ na „Neco“. Potom bude i to razeni o neco smysluplnejsi. :)

Jan Tvrdík
Nette guru | 2595
+
0
-

Jsem výrazně proti navrhované změně pořadí položek v dokumentaci. Současné pořadí je zcela úmyslně neabecední.

Abecedně seřazené odkazy do dokumentace můžete najít na https://nette.org/…cial/sitemap#….

hrach
Člen | 1834
+
0
-

Soucasne poradi je totalne k nicemu. Nema zadnou logiku. V cem je napriklad databaze mene dulezita nez Http request & response. Pro novacka uplne v haji. Pro cloveka ctouci dokumentaci je nedohladatelne.

vvoody
Člen | 910
+
0
-

Jan Tvrdík napsal(a):

Současné pořadí je zcela úmyslně neabecední.

Ale prečo?

Filip Procházka
Moderator | 4668
+
0
-

@Jan Tvrdík: Zde jsou abecedně pouze slugy z url, nikoliv titulky, což je dost matoucí, byť asi logičtější.

Editoval HosipLan (31. 8. 2012 18:24)

Grelek
Člen | 233
+
0
-

Jan Tvrdík napsal(a):

Jsem výrazně proti navrhované změně pořadí položek v dokumentaci. Současné pořadí je zcela úmyslně neabecední.

Abecedně seřazené odkazy do dokumentace můžete najít na https://nette.org/…cial/sitemap#….

Proč je to úmyslně? Vždyť to nemá žádný smysl!

Navíc, na sitemapě jsou seřazené abecedně pouze slugy.

LeonardoCA
Člen | 296
+
0
-

Já jsem vždycky nejvíce nadával, když jsem hledal odkaz na API. Pak mne napadlo si ho přidat do toolbaru prohlížeče a od té doby to že se ztrácí mezi ostatními odkazy neřeším :-)

Caine
Člen | 216
+
0
-

@LeonardoCA jo ten je taky pěkně schovanej:)

@Jan Tvrdík před víc jak půlrokem jsem se Nette učil a rozhodně jsem nejel podle toho pořadí, ale podle toho, co jsem aktuálně potřeboval a každou chvíli jsem musel číst celej ten seznam, abych našel to, co mě zajímalo (opruz)!

MartinitCZ
Člen | 580
+
0
-

@Grelek, @Caine +1

paranoiq
Člen | 392
+
0
-

díky @Caine.

obhájcům stávajícího stavu:

  • máte nějaké UX testy, které by dokazovaly vaše tvrzení, že tzv. „logické“ řazení komukoliv pomáhá?
  • můžete doložit proč jsou např. formuláře důležitější než databáze? (samozřejmě pro všechny položky v seznamu)
  • k čemu je dané uspořádání člověku, který z Nette používá třeba jen Laděnku a Mail?
  • dokážete akceptovat, že jsou lidé, kteří používají manuál jinak, než vy si představujete, že by ho měli používat?

proberte se ze svých pokusů o didaktický inženýring a seřaďte ten seznam normálně. ocení to drtivá většina uživatelů, včetně nováčků

update: předpokládat, že tzv. nováček je nesvéprávný debil, který není s to si vybrat ze seznamu témat, které si prostuduje je opravdu hloupé. nesnažte se myslet za ostatní

bazo
Člen | 620
+
0
-

robim s nette uz par rokov a stale hladam, co potrebujem, abecedne poradie by sa hodilo. minule som hladal obrazky trvalo mi dobrych 5 minut kym som nasiel, ze je to Zpracování obrázků.

Caine
Člen | 216
+
0
-

Navrhoval bych takovýto seznam, myslim, že takhle každej najde, co potřebuje;)
Pozn: tučně jsou změněné

AJAX
Anotace
Atomické operace
Auto-loading tříd
Cache
Databáze & ORM
Debugování a zpracování chyb (ladění)
Dependency Injection
E-maily
Formuláře
HTML
HTTP request & response
Komponenty a ovládací prvky
Konfigurace prostředí
Lokalizace
MVC & presentery
Nette\Object nebo jen Object?
Obrázky
Pole
Přihlašování & oprávnění uživatelů
Reflexe
Routování URL
Řetězce
Sessions
Stránkování
Šablony, Latte makra a helpery
Testování
URL
Validace
Vyhledávání souborů a adresářů

Jan Tvrdík
Nette guru | 2595
+
0
-

bazo wrote: minule som hladal obrazky trvalo mi dobrych 5 minut kym som nasiel, ze je to Zpracování obrázků.

Myslím, že je pomalu čas, naučit se používat svůj webový prohlížeč a internet obecně – považuji totiž za normální používat hledání jak na stránce (Ctrl+F v prohlížeči) tak pomocí Google.

Grelek
Člen | 233
+
0
-

Ale proč? Od dokumentace bych čekal, že přijdu a hned najdu, co hledám. Žádné CTRL+F.

Filip Procházka
Moderator | 4668
+
0
-

Prohlížeč to bude mít vždy najité dřív jak ty.

paranoiq
Člen | 392
+
0
-

napřed prohlásíme, že uživatelé jsou speciálové, kteří potřebují menu „správně“ seřazené od vyšší bytosti a když jim nevyhovuje, tak jim vynadáme, že jsou blbci a neumí vyhledávat. logika sama

hrach
Člen | 1834
+
0
-

Myslím, že je pomalu čas, naučit se používat svůj webový prohlížeč a internet obecně – považuji totiž za normální používat hledání jak na stránce (Ctrl+F v prohlížeči) tak pomocí Google.

Já si myslím, že je začít třeba používat logiku.

  • vyhledávní na stránce: prohlížeče IE, Firefox, Opera neumí vyhledet bez diakritiky
  • vyhledání googlem: dokumentace je v strasnym bordel stavu
    • polovina dulezitych veci je v plannete
    • duplicitni verze v aj / en
    • chyby ve smerovani (tuhle sem chtel najit coding aktualni coding standards… schvalne zkuste)

Koment o vyhledavani je mimo. Stale neznam duvod aktualniho poradi. Vymyslelo se to nekdy kolem verze 0.8, kdy byl framework uplne jinde (a list byl mnohem prehlednejsi diky subsekcim). Nazvy jednotlivych odkazu jsou spatne. Odkdy ma nette ORM? Ta uvodni stranka dokumentace je opravdu WTF a rada, ze mas pouzivat svuj vyhledavac urcite velmi potesi vsechny nove uzivatele frameworku, hlavne ty v zahranici.

redhead
Člen | 1313
+
0
-

Sama nutnost použití Ctrl+F (což je první věc, co při vstupu na dokumentaci dělám) je naopak důvod k předělání.

Filip Procházka
Moderator | 4668
+
0
-

@redhead má asi pravdu s tím, že nutnost používat CTRL+F na stránce zavání špatnou použitelností.

Hlavním „problémem“ je, že nette.org je především obsahový web. Kdy jste se naposledy k nějakému článku na wikipedii proklikali z hlavní stránky? To je přece hovadnina. Když použiju vyhledávání, budu tam minimálně o řád rychleji i než autor webu.

Zase je ale potřeba uznat, že malé postrčení ve formě účelného seřazení témat na hlavní stránce dokumentace může pár začátečník pomoct rozhodnout se, co si přečtou nejdřív.

A nebo taky ne. Přijde mi, že to, že někdo studuje dokumentaci od začátku do konce, je spíše velice výjimečný stav.

@hrach: je dost hloupý argument, že to prohlížeče neumí, protože můj to umí.


Raději to ale ještě jednou shrnu: je mi jedno jak si to seřadíte, já si budu používat vyhledávání a budu tam vždycky rychleji než vy :)

Editoval HosipLan (2. 9. 2012 11:54)

Jan Tvrdík
Nette guru | 2595
+
0
-

hrach wrote: prohlížeče IE, Firefox, Opera neumí vyhledet bez diakritiky

Proč bych hledal bez diakritiky, když jsem zvyklý psát s diakritikou a v dokumentaci je diakritika také používána?

tuhle sem chtel najit coding aktualni coding standards… schvalne zkuste

Ok, zkusil jsem.

chyby ve smerovani

Co tím myslíš?

Vymyslelo se to nekdy kolem verze 0.8, kdy byl framework uplne jinde (a list byl mnohem prehlednejsi diky subsekcim).

Jsi naprosto mimo. Opíráš se o historické skutečnosti, které zřejmě neznáš. Současné pořadí odkazů je (pokud vím) práce Davida Grudla a je navržené pro Nette 2.0 stable.

hrach
Člen | 1834
+
0
-

@Jan Tvrdík

Ok, zkusil jsem.

Koukam, ze te je lehke uspokojit. Jestli tobe staci prvni vysledek vyhledavani, ktery je nahore oznacen jako being revised a pouze v en… To je podle me nedostatene. Osobne me po nalezeni teto stranky hnala snaha, zda a) je novejsi verze b) zda je ceska verze. Tím sem prisel na to, ze stranka navic neni ani zarazena v en dokumentaci. https://doc.nette.org/…ibuting/code (proklik z doc.nette.org).

Jsi naprosto mimo. Opíráš se o historické skutečnosti, které zřejmě neznáš. Současné pořadí odkazů je (pokud vím) práce Davida Grudla a je navržené pro Nette 2.0 stable.

Tak predne se opiram o zkusenosti. Pokud srovnam doc 0.9 tak tam vidim uplne stejne razeni, akorat se do 2.0 droply subsekce. Kolik let ze trval vývoj 2.0? Tzn. kolik let je to stary navrch razeni? 3 roky vcetně trvani devitky, za tu dobu se zmenilo imo dost.

chyby ve smerovani

Co tím myslíš?

Pokud neexistuje stranka v danem jazyce, neda se prepnout na jinou jazykovou verzi. Clovek se musi vratit na predchozi stranu, tam prepnout jazykovou verzi a doufat, ze odkaz na stejne tema je tam taky.

@HosipLan
Vsak ja netvrdim, ze optimalizovanost pro vyhledavani je spatna. Ja jen souhlasim s nazorem, ze aktualni UI doc stranky je naprosto spatne. A na tento argument tu existuji jenom reakce typu, ze neumim pouzivat vyhledavac. Vyhledavani je dobre pouzit tehdy, kdyz vis co presne hledas.

Jan Tvrdík
Nette guru | 2595
+
0
-

hrach wrote:

@Jan Tvrdík

Ok, zkusil jsem.

Koukam, ze te je lehke uspokojit. Jestli tobe staci prvni vysledek vyhledavani, ktery je nahore oznacen jako being revised a pouze v en… To je podle me nedostatene. Osobne me po nalezeni teto stranky hnala snaha, zda a) je novejsi verze b) zda je ceska verze.

Kdyby byla novější verze, nemyslíš, že by na ni byl z té stránky vedl výrazný odkaz? Zda je české verze zjistíš jedním kliknutím na vlaječku.

Tím sem prisel na to, ze stranka navic neni ani zarazena v en dokumentaci.

Protože to není úplně stable verze, viz „being revised“.

Pokud srovnam doc 0.9 tak tam vidim uplne stejne razeni, akorat se do 2.0 droply subsekce.

Opět jsi mimo. Titulní stránka dokumentace Nette 0.9 je backportována z titulní stránky dokumentace 2.0 právě proto, že nová dokumentace měla tuto stránku přehlednější.

Kolik let ze trval vývoj 2.0? Tzn. kolik let je to stary navrch razeni? 3 roky vcetně trvani devitky, za tu dobu se zmenilo imo dost.

Stále jsi mimo. Ta titulní stránka pochází (pokud mě paměť neklame, mám ji špatnou) z června 2011 a její spuštění bylo spojené s Patrikovým incidentem.

bazo
Člen | 620
+
0
-

Jan Tvrdík napsal(a):

bazo wrote: minule som hladal obrazky trvalo mi dobrych 5 minut kym som nasiel, ze je to Zpracování obrázků.

Myslím, že je pomalu čas, naučit se používat svůj webový prohlížeč a internet obecně – považuji totiž za normální používat hledání jak na stránce (Ctrl+F v prohlížeči) tak pomocí Google.

a inak si v poriadku? hladam ocami, ako kazdy normalny clovek. myslim, ze je pomaly cas, prestat predpokladat, ze vsetci su ako ty

hrach
Člen | 1834
+
0
-

Stále jsi mimo. Ta titulní stránka pochází (pokud mě paměť neklame, mám ji špatnou) z června 2011 a její spuštění bylo spojené s Patrikovým incidentem.

Pamět te klame. Je to z 14. 7. 2010. Omlouvám se za chybu, je stará 2 a ctvrt roku. Tedy z doby, kdy byla v plánu Nette 1.0. https://doc.nette.org/cs/2.x?…

paranoiq
Člen | 392
+
0
-

co záleží na tom jaký byl historický vývoj, když je to blbě právě teď?

řazení je založeno na pocitu, že by to možná mohlo někomu pomoci, i když už je tu několik lidí, kterým to zcela objektivně nepomáhá, ale vadí

vvoody
Člen | 910
+
0
-

Aby boli všetci spokojný, navrhol by som zachovať aktuálnu úvodnú stránku dokumentácie a pridať stránku v zmysle registra so zoznamom od Caine kde by kľudne mohli byť duplicitné odkazy napríklad ŠablonyLatte

Editoval vvoody (2. 9. 2012 21:04)

Nox
Člen | 378
+
0
-

Dokumentaci se nikdo neuci tak, ze jeden den sedne a projde to vsechno podle doporuceneho poradi.

Já se tak naučil Nette, Doctrine atd. ;) asi výjimka

Šlo by to co píše vvoody … anebo to mít možnost přepnout, jako nastavení řazení na http://diskuse.jakpsatweb.cz/ s tím, že je otázka, co by bylo defaultně. Ale pokud by to tlačítko bylo jasné a viditelné, tak by na tom tolik nezáleželo.

Ondřej Mirtes
Člen | 1536
+
0
-

Mělo by to být seřazené podle abecedy. Kdo je proti, ať se jí doučí.

22
Člen | 1478
+
0
-

Určitě je pravda, že abecedně se hledá líp, zejména těm, co za součacným řazením žádný vyšší princip nevidí, takže +1 pro abecední seřazení.

Editoval 22 (3. 9. 2012 21:09)

Grelek
Člen | 233
+
0
-

Přijde mi, že se z diskuze staly „dva tábory“. Jeden je pro abecední řazení, druhý ne.

Co takhle dát na web nějakou anketu? Mohlo by se tam vyjádřit dost lidí, hlavně kdyby to bylo „na očích“, všimli by si toho i začátečníci.

Editoval Grelek (3. 9. 2012 21:19)

Filip Procházka
Moderator | 4668
+
0
-

Demokracie nefunguje :) A hlavně v Nette ne. Prostě budou padat argumenty tak dlouho, dokud David nerozhodne ;)

hrach
Člen | 1834
+
0
-

A nebo Honza Tvrdik, ktery by mel mit prava, ne? :D Ale tam to na zmenu taky nevypada :D

paranoiq
Člen | 392
+
0
-

HosipLan napsal(a):

Prostě budou padat argumenty tak dlouho, dokud David nerozhodne ;)

no tak už aby začaly padat. ze strany vyššího principu zatím nic :P

Filip Procházka
Moderator | 4668
+
0
-

Buď Veliký naše malicherné spory ignoruje, nebo mu vyhovuje současný stav :)

Caine
Člen | 216
+
0
-

Nemůžu si pomoct, ale cca 10 lidí chce abecední řazení a 2–3 ne..
Ještě bych se zeptal, kdo z těch, co nechtěj abecední řazení, tu dokumentaci skutečně využívá?:)

pekelnik
Člen | 462
+
0
-

Navrhuji aby stavajici nahodne poradi bylo zachovano a pokud bude detekovan stisk klaves Ctrl+F aby se to seradilo podle abecedy :D

Majkl578
Moderator | 1364
+
0
-

A co tam dát obě varianty a podle (bool) rand(0, 1) náhodně rozhodnout, jak se to zrovna vypíše? Uspokojí a naštve to oba tábory stejně. 


Ale teď vážně – aktuální řazení mi dává smysl, je to imho seřazené zhruba dle priority. Nicméně požadavek na abecední řazení taky chápu, pokud hledám něco konkrétního. Co tam dát podobnou funkci, jako má ApiGen:

Tj. přepnutí mezi přirozeným a abecedním řazením?

David Grudl
Nette Core | 8074
+
0
-

Jen pro zajímavost: neznám žádnou dokumentaci frameworku, která by měla abecední řazení (s výjimkou ZF, tam je to nutnost). Dokonce ani v knihách se to nepoužívá. Viz třeba Jakubova kniha, kde se může zdát, že není žádný důvod to tak neřadit.

Důvod, proč je to tak řazené, je ten, že v tomhle pořadí by měl čtenář dokumentaci číst. Souvisí s tím i šipky na konci každé strany.

Poté, co dokumentaci dočte, by asi víc ocenil abecední řazení, což by mohl zajistit nějaký přepínač.