Chvála MSDN dokumentace

14.2.2009 00:30 | Přečteno: 1405× | Rouhání největší

Nedá se nic dělat, je to prostě fakt. Těžko člověk hledá lepší referenční dokumentaci, než je ta, která je součástí MSDN. Zejména pokud potřebuji něco z JavaScriptu a DOM, je MSDN naprosto bezkonkurenční.

Dlouhá léta hovořím o tom, že jednou z největších slabin GNU/Linuxu a většiny svobodného softwaru obecně je dokumentace. Dokumentace, a to jak uživatelská k programům, tak zejména referenční k různým API, bývá neúplná, zastaralá a špatně organizovaná.

Před pár měsíci jsem potřeboval najít trochu méně obvyklé věci v JavaScriptu a HTML DOM. Veškeré pokusy dohledat to selhaly. Až na jeden jediný - Google mě zavál na stránky MSDN, kde jsem našel všechno, co jsem potřeboval. Navzdory tomu, že si Microsoft tyto věci přiohýbá k obrazu svému (tedy co funguje v IE, nemusí odpovídat standardům a hlavně nemusí fungovat v jiných prohlížečích), mně jeho dokumentace posloužila naprosto dokonale. Je úplná a výborně organizovaná.

Dal jsem si tedy MSDN dokumentaci (kterou jsem dříve používal prakticky jen při využívání Windows API) do záložek a k velké spokojenosti ji používám vždy, když si v JavaScriptu nejsem něčím jistý nebo něco hledám.

Takto nastavené laťce se (z toho, co běžně používám) přibližuje ještě tak dokumentace k Javě, PHP a Qt (byť microsoftí úrovně nedosahuje). Už třeba GNU C Library je problém, byť před 18 měsíci došlo k aktualizaci tehdy 6 let starý informací.

Před časem vznikl projekt lindevdoc, který sice vypadal nadějně, ale brzy skončil tak, jako většina takových projektů. Zájemci o přispívání k tvorbě obsahu odpadli a jeden Bluebear to sám nevytrhne. Připomínám to tedy jako inspiraci - vlak Microsoftu ujel opravdu o hodně veliký kus, bude hodně náročné se mu aspoň přiblížit. Ale bez kvalitní dokumentace to opravdu nejde a každý krok kupředu výrazně pomůže.

       

Komentáře

[Semo]

Mozno pre JS alebo DOM... Ale ked som programoval vo VS v C alebo v C++ a potreboval som dokumentaciu ku libc, tak nakoniec som aj tak koncil pisanim man nieco v Putty. Pretoze manualy su pisane absolutne exaktne a je z toho jasne, ze co MUSI byt splnene, co MOZE a co sa stane ak nieco z casti MUSI splnene nebude. Keby som pouzival iba MSDN, tak ku vsetkemu si budem robit par pokusov, aby som zistil ako sa to chova v hranicnych pripadoch.

Navyse libc nezastarava az tak rychlo, aby par rokov robilo vyznamny rozdiel pri beznejsich fciach.

[Luk]

Navyse libc nezastarava az tak rychlo, aby par rokov robilo vyznamny rozdiel pri beznejsich fciach.

Jenže ty běžnější funkce člověk používá často a nepotřebuje je obvykle hledat. Zato ty méně významné se nepamatují, proto je potřeba je najít. A když člověk nemá představu, jak se funkce jmenuje, "man" použije dost těžko. K tomu je právě potřeba ta strukturovaná dokumentace, kde se lze snadno orientovat a dojít k tomu, co je potřeba. glibc takovou dokumentaci sice má, ale mizerně použitelnou, spousta věcí v ní chybí, spousta je vysloveně obsolete (např. některá makra, která už ani nejsou v headerech - kupř. O_READ a další) atd.

[Jan Včelák]

Co konkrétně jste hledal, smím-li se tázat?

[Luk]

Různé drobnosti, například jak získat objekty/elementy určitého typu (např. ul) nebo jak provádět různé změny CSS stylu objektů.

[Jan Včelák]

Aha. Tak to zas takový libůstky nejsou. I když věřím, že v MSDN to mají pěkně zpracované.
Já si vždy postačím s JavaScript Reference.

[Luk]

Já si vždy postačím s JavaScript Reference.

To jsem dříve zkoušel používat. Ale nevyhovovalo mi to, nebyl jsem schopen najít to, co jsem potřeboval.

[s0]

Já teda beru jako etalon kvalitní dokumentace Qt. MSDN mám na úrovni Oracle - je to neskutečně obsáhlé, ale najít v tom rychle potřebnou věc vyžaduje hromadu zkušeností, štěstí a hodně trpělivosti.

[|🇵🇸]

Já mám zase dobrou zkušenost s dokumentací Javy, neříkám sice, že je to ideál, ale je v tom všechno a je to aktuální. Dokumentace Pythonu také není špatná. A k HTML/CSS používám Jak psát web, ačkoliv je mírně zastaralý.

S tím MSDN souhlas. Kdykoliv jsem něco hledal u MS (dokumentace-nedokumentace), skončilo to kolapsem a následným googlením. Nemám rád věci, které si myslí, že ví, co chci, lépe než já.

[podlesh]

Java má v tomto jednu praktickou výhodu. K samotnému JDK a k většině knihoven které člověk potřebuje je ta nejlepší dokumentace vůbec - zdrojáky.

Jistě, kvalitní dokumentace je nedocenitelná při psaní, ale při hledání chyby jsou mnohem lepší zdrojáky - tam jsou vidět okrajové případy které nikoho nenapadlo nezdokumentovat. A také jsou tam vidět bugy, ty vesměs také v dokumentaci chybí

[Josef Kufner]

Kdyby zdrojáky byly ta nejlepší dokumentací, dokumentaci bysme nepotřebovali.

[Luk]

A k HTML/CSS používám Jak psát web, ačkoliv je mírně zastaralý.

Též používám. Zastaralost většinou nevadí, protože stejně člověk musí brát ohledy na starší prohlížeče (zejména IE 6). Právě problematika starších prohlížečů je hlavní důvod, proč se tam dívám.

[Pavel Stárek]

Dokumentace Pythonu také není špatná.

Špatná není, ale zázrak to taky žádný není. Ze všech open source projektů se mi líbí dokumentace ke knihovně Qt ač tu knihovnu (zatím) nepoužívám.

[kralyk z abclinuxu]

Já teda beru jako etalon kvalitní dokumentace Qt.

+1 a skvělá je taky její integrace do QtCreatoru.

[Viliam Púčik]

+1 taktiež pre Qt dokumentáciu. Človek hneď nájde to, čo potrebuje.

[Salamek]

dokumentace QT ? link by nebyl bo mi z google vypadly jen jisté útržky (nebo jsem líně hledal)

[kralyk z abclinuxu]

tudy
Ale vono nejde (jen) o tu webovou verzi, důležitá je hlavně offline verze - Qt Assistant propojený s kupou demíček a názorných příkladů.

[kralyk z abclinuxu]

zejména referenční [dokumentace] k různým API, bývá neúplná, zastaralá a špatně organizovaná

no nebo taky vůbec žádná, že...

[Deleted [8409]]

Musím souhlasit, sice na MSDN hledám hlavně WinAPI, ale ta dokumentace je fakt dobrá. Dokumentaci na takové úrovni jsem k linuxovým knihovnám bohužel neviděl. Chtělo by to centralizovaný server s dokumentací a hlavně kategorizací linuxových knihoven, ale nevim jestli je něčeho takového open-source komunita schopná. Ale nechce to jen dokumentaci, ale i hodně příkladů, kde programátor uvidí, jak se to API správně používá.

PS: Jinak pokud děláte v JS, je mnohdy nejlepší podívat se do jiných knihoven, protože oni většinou všechny ty nekompatibility musí řešit:)

[Bluebear]

Díky za reklamu

Zdůrazňuji, že projekt lindevdoc zatím není mrtvý a stále se snažím ho updatovat (poslední týden jsem, pravda, nestihl nic, což je dáno pravidlem nejdříve práce - potom zábava).

Takže, kdykoli bude mít kdokoli chuť, může něco přidat (není nutno se ani registrovat, i když registrace je automatická) - už nějakou dobu to běží na MediaWiki, takže formátování je dobře známo. Struktura stránek taky není nijak složitá, a bude-li třeba s něčím poradit, jsem k dispozici jak na mailu, tak na jabberu.

[Martin]

Já tedy o problematice vím velké kulové, takže těžko nějak pomůžu, ale kde všude jsi tomu zkoušel dělat reklamu? Tohle je totiž jeden z mála smysluplných webových projektů, které jsem tady zatím viděl někoho inzerovat (vlastně je úplně jediný, na který si můžu vzpomenout) a byla by fakt škoda, kdyby vyšuměl do ztracena.

[Luk]

kde všude jsi tomu zkoušel dělat reklamu?

Přinejmenším tady na abíčku. Trochu byl ale problém v tom, že například já jsem po počátečním nadšení ztratil motivaci - poté, co mi nějak záhadně (nevím, čí to byla vina) zmizela cca hodinová práce. Od té doby jsem na to nesáhl - a když už mám chuť na práci tohoto druhu, raději krmím Wikipedii.

[Martin]

Přinejmenším tady na abíčku.

No, k tomu jsem tak trochu směřoval. Ne, že bych nebyl přesvědčen o tom, že se tady vyskytuje spousta lidí schopných k tomu projektu kvalitně přispívat, ale... Třeba rozeslání oznámení na pár velkých anglicky mluvících mailing listů orientovaných na linux by myslím udělalo mnohem větší reklamu. Podobná dokumentace totiž opravdu chybí a určitě si to spousta lidí uvědomuje (a klidně by i přiložili ruku k dílu, jen o tomto projektu třeba neví).

[Filip Jirsák]

Mozilla Developer Center znáte? Konkrétně: DOM a JavaScript 1.5.

Nemohl byste na oplátku (za odkazy) napsat návod, jak to MSDN používat? Pokaždé, když potřebuju dokumentaci „jak to dělá MSIE“, mám problém vůbec tu dokumentaci najít. Pravda je, že když už jí konečně najdu, je tam přehled opravdu všech objektů, vlastností a metod. Akorát se tam někdy člověk to podstatné nedozví, nebo jsou tam nesmysly (ale to asi v každé dokumentaci).

[|🇵🇸]

Akorát se tam někdy člověk to podstatné nedozví, nebo jsou tam nesmysly (ale to asi v každé dokumentaci).

Cílem je přeci zmatení nepřítele! Jinak by tu dokumentaci nikdo nedělal... ^_^

[Luk]

Mozilla Developer Center znáte? Konkrétně: DOM a JavaScript 1.5.

Neznám. Děkuji za odkazy, podle prvního nakouknutí vypadá to zajímavě.

Nemohl byste na oplátku (za odkazy) napsat návod, jak to MSDN používat?

Na co návod? Vždyť je to jednoduché. Já to používám tak, že si buď proklikám ten strom vlevo a najdu si, co potřebuji (například Web development -> HTML and CSS -> HTML and DHTML Reference -> Objects -> ...), anebo si to nechám vyhledat.

[Filip Jirsák]

Aha, ono je to momentálně přímo pod MSDN Library a člověk se nesmí nechat zmást odkazem „Vývoj pro web“, který je hned na titulní stránce MSDN. Teď ještě aby to takhle nějakou dobu vydrželo…

[Jan Včelák]

Mně přijde ten strom vlevo dost nešťastnej. Proklikat se ním je asi nejobtížnější část hledání.

Ale nevím, kde vzít tu jistotu, že mi věci, co tam nejdu, poběží v IE, FF, Opeře, Chromu, ...

[Luk]

Ale nevím, kde vzít tu jistotu, že mi věci, co tam nejdu, poběží v IE, FF, Opeře, Chromu, ...

Jistota není. Tím spíš není jistota, že bude v IE (který je bohužel ještě stále většinový) fungovat to, co je v dokumentaci Gecka (viz výše). Nejlepší je obě dokumentace kombinovat a samozřejmě všechno vydatně testovat.

[Josef Kufner]

Lindevdoc je imho špatná cesta. Krmit ručně nějakou wiki stojí daleko víc práce než to kdy komu pomůže.

Raději bych tady viděl nějaký katalog dokumentace ke všemu možnému, do kterého by se ručně dalo akorát pár odkazů (minimálně na hlavní stránku a rejstřík) na originální dokumentaci přímo na webu projektu. Pak ještě by bylo potřeba ručně popsat formát rejstříku, aby vyhledávání bylo dostatečně spolehlivé. Zbytek by mohl být plně automatický.

Nějaký robot by to postahoval, proindexoval a čas od času updatnul. Výsledek by byl přístupný přes unifikované rozhraní, které by poskytlo základní navigaci a vyhledávání. V důsledku bysme měli obrovský repositář trvale aktuální dokumentace.

A i kdyby to bylo bez robota, samotný katalog kde která dokumentace je, by byl velmi užitečný.

[Luk]

Krmit ručně nějakou wiki stojí daleko víc práce než to kdy komu pomůže.

To není pravda. Ty informace zhusta nejsou k dispozici nikde a každý, kdo by je potřeboval, stráví desítky minut až hodiny prohrabáváním se zdrojáky glibc a/nebo kernelu, aby zjistil, jak funguje jedno jediné ioctl() volání. Doplnit to do wiki už je záležitostí pár minut a pomůže to všem, kdo se dostanou do stejné situace.

A i kdyby to bylo bez robota, samotný katalog kde která dokumentace je, by byl velmi užitečný.

To sice ano, ale to by ta dokumentace musela vůbec někde být, a to v přijatelné kvalitě. Jinak to postrádá smysl.

[Josef Kufner]

Tak mi ukaž něco co je na lindevdoc a jinde není. Co jsem namátkou koukal, tak prosté man podá odpověď daleko lepší a rychleji.

Další výhodou onoho katalogu by také byla možnost seskupit i nejrůznější tutoriály a články spolu s referenčním manuálem do daleko obsáhlejšího celku a za vynaložení minima úsilí (a se starostí o autorská práva na úrovni google cache).

[|🇵🇸]

Dost keců, je čas jednat! ^_^

[Luk]

Tak mi ukaž něco co je na lindevdoc a jinde není.

Tak zaprvé, na lindevdoc skoro nikdo nepracoval, tudíž tam těžko může být obsah. Zadruhé například obsah, který jsem tam kdysi vkládal (a který tam z nějakých důvodů není nebo ho nemohu dohledat - nepočítám to, co zmizelo už tehdy), opravdu jinde pohromadě nebyl. Byl to popis různých ioctl() příkazů týkajících se disků.

Co u lindevdoc v současné podobě vidím jako největší problém (kromě toho, že se na tom moc nepracuje), je celková struktura. Návštěvník tam vleze a neví jak dál. Má tam tři položky (Guide:Contents | Category:Glossary | Help:Contents), ze kterých není příliš jasné, kam se vydat.

[Josef Kufner]

Čímž se kruh uzavírá a projekt se nemá moc šancí rozběhnout.

Navíc dokumentace patří k programům a má být udržována současně s programem. Jinak je už předem odsouzena k záhubě.

[Bluebear]

Navíc dokumentace patří k programům a má být udržována současně s programem.

Teoreticky je to naprostá pravda, ale:

1) Jak přimět vývojáře, aby tu dokumentaci psali? (Psychologická bariéra: vývojář svůj projekt zná prakticky zpaměti, tudíž může mít dojem, že je všechno naprosto jasné a dokumentace ani není potřeba, nebo jen pár komentářů v nepřehledných místech.)

2) Vývojář umí psát kód, ale ne nutně umí psát dokumentaci; na druhou stranu jen málokterý projekt má tak silnou komunitu, aby si mohl dovolit vydržovat specializované dokumentátory. (Dokonce ani tak důležitý a významný projekt, jako je glibc, má dlouhodobě problém s nedostatkem dokumentátorů.)

[Josef Kufner]

Celkem dobrý podmět pro psaní dokumentace je snaha o sehnání uživatelů a testerů. Od vývojáře stačí, aby ke každé funkci v API napsal do komentáře dvě věty, co to dělá. Zbytek se vygeneruje a když je alespoň nějaký malý základ, je daleko jednodušší přispět. Takže bych raději viděl kvalitní a jednoduše použitelný nástroj (sadu nástrojů) na dokumentování, který by odstraňoval co nejvíce takových "ale" a řešil i přispívání nejkratší možnou cestou přímo ke zdroji. Přecejen, mediawiki je k tomuhle trošku nešikovná.

Vím, že nějaké takové nástroje už existují, Gtk i Qt a spousty dalších knihoven je používají. Ale zjevně nejsou tak dobré, jak by mohly být (a jak by bylo potřeba).

(S tím, co jsem psal před chvílí se to nevylučuje, tohle je jen pohled z druhé strany problému.)

[Luk]

Takže bych raději viděl kvalitní a jednoduše použitelný nástroj (sadu nástrojů) na dokumentování

Není mi jasné, co si představit pod pojmem "nástroj na dokumentování". Je to třeba doxygen (který vezme "strukturované komentáře" v kódu a vygeneruje z nich HTML/PDF/TEX/man/RTF/... dokumentaci)? Nebo je to taková ta funkce například v Netbeans, která pomocí klikání umožňuje snadno přidávat ony strukturované komentáře ke třídám/metodám/... a ukazuje, zda se na něco nezapomnělo? V obou případech tady kvalitní nástroje máme, stačí je používat. Že to vývojáři zhusta nedělají, je druhá věc (já se ovšem mohu pochlubit, že se o tvorbu dokumentace ke kódu snažím, jak se každý může přesvědčit například tady nebo tady).

[Josef Kufner]

Tož to jo. Tenhle směr výroby dokumentace existuje a nástroje jsou celkem dobré... to nepopírám.

Vem si ale pohled ze strany programátora-uživatele, který zkoumá jak nějaká, nepříliš dobře zdokumentovaná knihovna funguje a snaží se jí použít ve svém programu. Pracně zjistí co a jak, uloví někde pár příkladů a chce své poznatky někam umístit. Asi se shodnem, že lepší místo, než je samotná dokumentace knihovny, neexistuje. Otázkou však je, jak?

Uvažujme přiměřenou míru lenosti, tedy stahování zdrojáků (instaloval jen balíček z distribuce), hledání v nich a dopisování dokumentace tam příliš nepřipadá v úvahu. Na druhou stranu, vygenerovanou dokumentaci na webu projektu už zná a pokud by tam bylo tlačítko "Upravit", za kterým by byl kousek php a o kus dál ležel generátor patchů, které by stačilo čas od času začlenit...

[Bluebear]

Co u lindevdoc v současné podobě vidím jako největší problém (kromě toho, že se na tom moc nepracuje), je celková struktura. Návštěvník tam vleze a neví jak dál. Má tam tři položky (Guide:Contents | Category:Glossary | Help:Contents), ze kterých není příliš jasné, kam se vydat.

Výborně, tohle je konkrétní, jasný problém - s tím se dá něco dělat. Píšu si.

Ano, vím, že se na tom teď moc nepracuje, bohužel. Má to objektivní příčinu: sto procent autorů má momentálně v zaměstnání napilno.

[Bluebear]

Lindevdoc je imho špatná cesta. Krmit ručně nějakou wiki stojí daleko víc práce než to kdy komu pomůže.

Mnojo... dost možná máš pravdu. Pokud to budu dělat sám, tak máš pravdu natuty.

Raději bych tady viděl nějaký katalog dokumentace ke všemu možnému, do kterého by se ručně dalo akorát pár odkazů (minimálně na hlavní stránku a rejstřík) na originální dokumentaci přímo na webu projektu.

Takových projektů už několik existuje. Jejich problém je IMO se zastaráváním odkazů. Dokumentační weby se sice nepřesouvají často, ale tu a tam přece; nebo se mění jejich organizace a URL přestávají platit (což by se sice dít nemělo, ale stává se) a při velkém počtu odkazů to začíná být citelné.

Nějaký robot by to postahoval, proindexoval a čas od času updatnul. Výsledek by byl přístupný přes unifikované rozhraní, které by poskytlo základní navigaci a vyhledávání.

To je pravda, tím by se také vyřešil (nebo dejme tomu výrazně omezil) problém s mizejícími odkazy. Zároveň by bylo všechno pohromadě, takže by - za předpokladu rychlé linky - šlo vyhledávat se stabilními latencemi.

Mám ale pocit, že napsat robota, který by to dělal, by nebylo nijak snadné, protože různé dokumentace jsou k dispozici v různých formátech. U těch dokumentů, které jsou generovány z nějakého zdrojového textu (ať už to je přímo zdrojový kód dané knihovny/modulu, nebo Docbook, apod.) by stačilo, aby robot znal tyto formáty; ale u dokumentů, které mají jen jediný formát, který není přesně definovaný (wiki, HTML v Drupalu apod.), by to vyžadovalo nějakou heuristiku.

[Deleted [8409]]

Proč na to jít složitě, když to jde mnohem jednodušej :)

Dokumentace by opravdu měla být udržovaná hlavně v knihovně a díky dokumentačním nástrojům exportována do různých formátů. Jenže přesně jak říkáte, dokumentace je na webu v různých formátech a není v lidských silách napsat bota pro všechny možné formáty.

Co na to jít jinak ? Podívejte se například jak funguje seznam zboží. Poskytnete URL, na které si jejich bot dokáže získat potřebné informace, ty už si narve do DB a používá pro svoje potřeby. Takže by vám stačilo v budoucnu jen to, že si každý nový projekt (asi knihovna) může požádat o registraci a poskytne dokumentaci v předem definovaném formátu - podle mě jednoduché pro obě strany. Navíc síla vyhledávání (kde znáte co je funkce, co třída, namespace, atd) by mohla být fakt veliká.

Mi ovšem na lindevdoc nejvíc vadí kategorizace. Bez hierarchické struktury není podle mě možné uspořádat tak ambiciózní projekt. Potřebujete kategorizovat a škatulkovat každou novou knihovnu, aby v tom byl přehled (podle mě jsou kategorie jsou mnohem lepší než štítky, vůbec nejlepší je jejich kombinace). Prostě ten styl wiki mi přijde nepřehledný a oproti MSDN je to pro mě nepoužitelné a z dlouhodobého hlediska asi neudržitelné.

[Josef Kufner]

Jo, s různými formáty by trošku problém byl, ale v zásadě stačí, když dokumentace bude mít obsah a rejstřík. Obsah pro uživatele, rejstřík pro robota. Jednu HTML stránku s hromadou odkazů není problém rozparsovat do použitelné podoby.

V hodně obskurních případech by se možná dalo promluvit s autorem, jestli tomu nechce trochu pomoct. Ale pokud to bude malý projekt s malou dokumentací, stačí fulltext (a třeba přizvednout váhu nějaké konstrukce použité pro označování názvů funkcí). U velkého projektu bude dokumentace generovaná a ten rejstřík už někde bude.

Pak tady máme pár stovek studentů, co každý semestr škemrají o zadání semestrální práce...

[pavlix]

Je naprosto bezkonkurenční už proto, že jako jediná postihuje velkou část microsoftích nestandardních úprav.

[happy barney]

Ok, možno neviem používať niečo také skvelé a úžasné, možno neviem používať ani google ... nájdite mi prosím popis, prečo v nasledovnej situácii IE zblbne a Opera/Mozilla bez problémov idú ďalej:

ls -a:
.htaccess
.htpasswd
index.html
protected.cgi

index.html obsahuje iba meta http-equiv="refresh" content="0;protected.cgi"

[Luk]

Tohle blbne ze dvou důvodů. Zaprvé je ta syntaxe chybná, což je bez diskuse. Zadruhé je v IE zjevně chyba, kterou by bylo potřeba ohlásit - i když je otazné, jestli to někdo bude řešit, protože refresh je označen jako obsolete.

[happy barney]

vypísal som len podstatný obsah, tagy sa mi nechcelo
len pre info, chyby imho majú v history module:
1. najprv si vypýta stránku, dostane auth request
2. po prihlásení pýta si ju znova, tentokrát s If-Modified-Since, a to robí, až kým ho človek nezostrelí
takto sa chová 5, 5.5, 6, 7, ostatné nemám k dispozícii

[Luk]

vypísal som len podstatný obsah, tagy sa mi nechcelo

Chyba byla už v tom napsaném - správně by bylo kdyžtak toto (nejsem si teď navíc úplně jist, jestli by URL neměl být absolutní - např. u Location tomu tak je):

<meta http-equiv="refresh" content="0; url=protected.cgi">