MSDN
-
Managed to get this today while trying to troubleshoot a database problem.
Notice how it somehow managed to embed the new MSDN UI within the old one, but that really is the least of MSDN's "issues".
Here's a few more:
- MSDN search is f'ing useless. Since their last update, they now use the MSN/Live! search engine, an engine that is optimized for searching the web. The web is a completely unstructured medium with no central control and no reliable metadata.
Microsoft fully controls MSDN. It has structure and metadata. See why a generic search engine is less than optimal? Besides that, even Google does a far better job that MSDN's built-in engine.
Thankfully, the Visual Studio help browser has a better search engine, with some basic filtering, when it works. - Every so often, Microsoft decides to reorganize MSDN (or at least re-skin it), breaking everybody's bookmarks. Combined with the above, even once you've found something in MSDN you won't be able to refer to it for more than a few months.
Even better, while this is happening, it usually breaks the Visual Studio help browser as well. - MSDN contains developer documentation for every Microsoft product. Why is there no way to search only in the products I'm interested in in the online version? If I'm looking for .Net documentation, I don't care about Win32, Windows CE, DirectX, Microsoft Office, Windows Scripting Host or any of the other crap. I would also like to be able to search by version of the product. If I'm writing for an ASP.Net server that only has version 2.0, I couldn't care less about LINQ and all the other stuff that was added in 3.5. In fact, it seems that now VS 2008 is out, all mention of .Net 2.0 has disappeared from MSDN's searchable articles, being banished to the "previous versions section" (non-searchable).
- For .Net documentation, the language filter is broken. Why is it that when it is set to "C#" I still get boxes telling me that it is "Not applicable" for XAML. If I wanted XAML information I would have ticked that on the language filter!
- I often come across "informational" pages on MSDN with lists of classes that are not linked to their documentation and sometimes broken links. Seems that even Microsoft employees can't handle the constantly changing URLs of MSDN.
- The Visual Studio help browser, while better than the online version has it's own issues:
- There seems to be no benefit to installing documentation locally (even in "Try local first" mode). All content come from the internet anyway and it simply doesn't work when there is no internet connection.
- The browser keeps no history (so I can't find the useful article I found yesterday, unless I remembered to bookmark it, but even then I will lose it next time MS reshuffle the thing) and neglects to save any of my options. Every time I start it I have to set the language filter and search options.
- Why doesn't it set the language and search filters automatically depending on what I'm editing in Visual Studio? (Of course, allow me to override it if I want.) If I'm editing a Windows Forms project written in C# then set those options. If it's a ASP.Net site in Visual Basic, set those. If it's a multi-language project, set both languages. What's so hard
- Most function documentation pages tell you barely any more than the function prototype. Sometimes they are inaccurate. Usually you have to experiment to find out what happens in edge cases. They rarely link to informational pages.
- All of the .Net class library documentation is organised by class name. If I'm trying to work out how to do something, I usually don't know the name of the class! How about organising by use or providing me with inheritance trees? (Inheritance tress are a really good way of finding the right class in OO langauges. Look at the way the Mono docs are organised to see how MS should have done it.)
Seriously. OSS projects (usually) get documentation right. Look at the GNU C library docs, Boost, SDL, GTK(mm). Most of these don't even have a search function and are sometimes incomplete, but they are still well-organised and grouped in meaningful ways (usually with multiple methods of navigation). It helps that each project has a separate set of docs rather than one monolithic database.
It's this sort of thing that has driven me away from MS solutions for my hobby programming (stuck with it at work). I learned to program in MS BASIC variants (although the best VB6 documentation I found was the VBA help file that shipped with Office, MSDN was useless even back then), but now I use mainly OSS frameworks in C++ (sometimes Mono and some scripting).
If Microsoft really want to keep their stranglehold on IT, they urgently need to fix their developer documentation, the more programmers they drive to cross-platform OSS frameworks, the easier it will be for users to jump ship.
- MSDN search is f'ing useless. Since their last update, they now use the MSN/Live! search engine, an engine that is optimized for searching the web. The web is a completely unstructured medium with no central control and no reliable metadata.
-
wow, what a thought out, through wtf.
maybe you should be using java, their api page doesnt suck! ZING!
-
I also hate the MSDN page...
-
@petvirus said:
wow, what a thought out, through wtf.
maybe you should be using java, their api page doesnt suck! ZING!
Yeah...but then you'd have to use java.
ZING! ;)
-
Faved and 5-starred.
I've been using MS tools since the beginning as well, but the MSDN is an uber-WTF. Really.. how hard is it to "finalize" a version's documentation and keep it in a static location. I do so many Google searches that result in forums and whatnot, that then in turn link to the MSDN (from a year or more ago), but then those links are broken. WTF. VB6 has not changed IN A LONG TIME. And, as you pointed out, they can't even keep .NET 2.0 in one location even though it's not that old. The whole works is borked. When the documentation provides examples, I can figure out how to link it all together. But, also as you pointed out, many times it's simply the prototype. What good is that?! It would be nice if there was a Wiki for .NET somewhere. That way we can pool everything that we find instead of having to rely on hundreds and thousands of scattered sites containing examples.
-
They really should have printed the screenshot of the new UI inside the old UI, put it on a wooden table, taken a photo and posted it.
-
I agree that the online version of MSDN is absolutely horrible for finding anything. The only thing I use the online MSDN for is featured articles, blogs, and the like. I just setup my locally installed MSDN library to use the local stuff - it works when offline so I'm not sure what's up with your install. The other thing that helps for the local install is to choose a manual install and deselect the crap you don't need.
-
I'm not sure why you consider yourself to be stuck with Microsoft at work. Unless you meant "for the time being." I'll assume that's what you meant.
I've always found PHP to have good online documentation, unless you want to start talking about PEAR. A lot of projects on PEAR are like "well we thought this project would be neat, but haven't written any code yet. But we thought of it first!" I know this forum's feelings on PHP, but I thought I would just throw that out.
-
@AbbydonKrafts said:
It would be nice if there was a Wiki for .NET somewhere. That way we can pool everything that we find instead of having to rely on hundreds and thousands of scattered sites containing examples.
Keeping such a site free of WTFs would be a non-trivial task, though.
-
@petvirus said:
maybe you should be using java, their api page doesnt suck! ZING!
In my opinion, PHP has the best online documentation available in one place of any language I've used.
-
My experience with online documentation.
PHP: Very well documented, user comments are usually crap, they should really read through the comments and purge them, some are actually really good though, and many mistakenly implement another function of php by abusing the one on the documentation page.
MSDN: Same state as PHP from what I've seen. Be damned if you can actually find what you're looking for. It's there I swear it is.
Java: After 3 hours I gave up looking for documentation and therefore gave up on the language itself. I was looking how to make a java applet for browsers, I'm still interested, but not actively looking.
C/C++: The basic stuff is very easy to google for, pity the standard costs $$, generally I just use books though (Complete guide to C++ fourth edition)
HTML: Same state as HTML with the exception that I've memorized it mostly.
JavaScript: Same as C/C++ seems to be more prone to newbie docs though.
Perl: I think it's all there, some pages could be split up (one with predefined variables as an example) and more tutorials would be nice.
Personally I think that PHP's pervasive documentation is it's key to success, its over crappiness (naming convention people, everything else appears to be be fixed in PHP 6) is its downfall.
-
@petvirus said:
maybe you should be using java, their api page doesnt suck!
Yeah the java API documentation is way easier to find stuff in than the .net one.
On the whole i find msdn relatively useless, the searching is absolutely hopeless, google usually does a better job of finding stuff on MSDN than the MSDN search does.
I find the layout quite strange sometimes too, they fixed it a couple of revisions ago but i remember when you went to look at a class definition the first page you saw was about thread safety etc. and there was a tiny little link to the class members. Thread safety is important but honestly the first thing i want to see when looking at a class is it's members and the link to get to them was actually quite difficult to find. Although with intellisense i find i rarely need to look up stuff like that anymore.
Conclusion: if MSDN comes up in your google search results check it out but otherwise don't bother.(for c# stuff anyway)
-
@emurphy said:
Keeping such a site free of WTFs would be a non-trivial task, though.
But it would be easier for those in the know to spot than, say, someone slipping bogus information into the Wikipedia article about the Dogons.
-
<deleted>
Farkin' "Delete" button doesn't work on this thing!
-
@Lingerance said:
C/C++: The basic stuff is _very_ easy to google for, pity the standard costs $$, generally I just use books though (Complete guide to C++ fourth edition)The draft Standards are free, and are usually close enough for most things.
HTML: Same state as HTML with the exception that I've memorized it mostly.
I'm assuming there's a typo in there. I'll be darned if I can figure out what it was meant to be though.
-
@PJH said:
@Lingerance said:
C/C++: The basic stuff is very easy to google for, pity the standard costs $$, generally I just use books though (Complete guide to C++ fourth edition)The draft Standards are free, and are usually close enough for most things.
HTML: Same state as HTML with the exception that I've memorized it mostly.
I'm assuming there's a typo in there. I'll be darned if I can figure out what it was meant to be though.its a recursive sentence ...
good thing my stack is shallow ...
-
And let's not forget that sometimes the information on MSDN is drastically, horribly wrong, in the "doing what this says will create subtly broken code that will haunt you forever" sense. The bits that explain what MS software does are usually right, but the advice on how to use it is far less reliable.
-
@PJH said:
@Lingerance said:
Fixed, I don't use online docs that much unless I need to find out that very freaking long doctype string.HTML: Same state as [b]C++[/b] with the exception that I've memorized it mostly.
I'm assuming there's a typo in there. I'll be darned if I can figure out what it was meant to be though.
-
@Lingerance said:
@PJH said:
@Lingerance said:
Fixed, I don't use online docs (for HTML) that much unless I need to find out that very freaking long doctype string.HTML: Same state as [b]C++[/b] with the exception that I've memorized it mostly.
I'm assuming there's a typo in there. I'll be darned if I can figure out what it was meant to be though.
-
@Lingerance said:
PHP: Very well documented, user comments are usually crap, they should really read through the comments and purge them, some are actually really good though, and many mistakenly implement another function of php by abusing the one on the documentation page.
Except for the fact that some of the more exotic functions are not documented past the prototype and that most of the comments are useless, php.net is documentaton done right. Not only is most of the documentation accurate and thorough, you also get usage examples and a very useful search function. Usually, if you need to look up something, just start a browser and enter "php.net/<topic>" and you get presented with either the page you're looking for or a list of probable matches. The topics are organized in a sensible way and it's relatively easy to find what you need even if you have no idea how it's called.
The documentation is a large part of why PHP is still my scripting language of choice. Python is nice, but compared to PHP its documentation is just painful to work with. Ditto for Ruby.
-
> Java: After 3 hours I gave up looking for documentation and therefore gave up on the language itself. I was looking how to make a java applet for browsers, I'm still interested, but not actively looking.
This complicated google query "java applet" got me to sun's Applets tutorial page. I can't figure out what about it was that difficult.
-
@asuffield said:
And let's not forget that sometimes the information on MSDN is drastically, horribly wrong, in the "doing what this says will create subtly broken code that will haunt you forever" sense. The bits that explain what MS software does are usually right, but the advice on how to use it is far less reliable.
My favourite is 'GetDiskFreeSpace'. This USED to be documented that if the free space was over 2GB it would be capped at 2GB. That worked fine until NT4 SP4 was released, when suddenly any bigger disks were reported as <free space> MOD 2GB - which obviously has issues if your disk has 2.00001GB free and this function is used for deciding whether you can install some software.
Nowadays, it's just documented as 'it doesn't work properly on disks over 2GB'. probably because they couldn't make it work as it used to work any more, and they couldn't be bothered to fix it because GetDiskFreeSpaceEx was available in NT4 and 95 OSR2 and later. (NT 3.51 and the original 95 still need to use GetDiskFreeSpace though)
Oddly, I've just looked on the online MSDN, and apparently 'GetDiskFreeSpace' requires Windows 2000 Pro, XP, Vista, or Windows 200[038] Server. All mention of NT, 95, 98, ME has totally disappeared! So, according to the online MSDN if you want to find out how much free disk space there is on ANY version of Windows you're stuffed.
My Visual Studio 2003's copy of MSDN shows it correctly as being supported by NT/95 or later. I wonder when the rest of MSDN will deny the existence of NT and 95/98/ME as well!
-
@sepi said:
This complicated google query "java applet" got me to sun's Applets tutorial page. I can't figure out what about it was that difficult.
D'oh. Usually I forgo using google if the site has integrated search, I keep forgetting that hardly anyone can do it even remotely well.
-
@AbbydonKrafts said:
those links are broken. WTF. VB6 has not changed IN A LONG TIME. And, as you pointed out, they can't even keep .NET 2.0 in one location even though it's not that old. The whole works is borked.
But of course. MS don't want anyone using VB6, they want developers to pay for the new version every time one comes out. VB6 is no longer supported, so why should they even provide the documentation?
-
@m0ffx said:
But of course. MS don't want anyone using VB6, they want developers to pay for the new version every time one comes out. VB6 is no longer supported, so why should they even provide the documentation?
That's all fine and dandy if you're trying to force a regular home consumer to do that. But a lot of businesses are hardasses about sticking with current technology. The C# work I do is in Express. Right now I'm redoing a VB6 application as a C# Windows service. If Express (or other free IDEs such as SharpDevelop) didn't exist, I wouldn't be able to do that since the company will not pay for new development tools (the CTO insists we use their lunatic Java "framework" instead). Also, some companies just have too large of applications to be forced to rewrite them.
-
In addition to everything the OP said, what about MSDN's failure to keep in sync with what's actually implemented?
Couple times now I've run into documentation explaining how to do just what I need on MSDN. So I read up and learn. Then when I try to use it: E_NOT_IMPLEMENTED or whatever. First time I had this problem I figured I must just not have the newest libraries or something. Wrong. It was never implemented at all. So I go back to the MSDN documentation to check, and surprise, no mention of this.
Unfortunately I don't remember what it was I was trying to use. Something network related. Maybe it's implemented now... Anyone else ever run into this or am I just crazy?
Luckily, I no longer use any Microsoft-proprietary stuff so I can avoid MSDN completely.
-
The real WTF is their authentication system. "Welcome, so and so. Sign in!"
Their pages can't even decide whether or not you're authenticated.
-
@ShatteredArm said:
The real WTF is their authentication system. "Welcome, so and so. Sign in!"
Their pages can't even decide whether or not you're authenticated.No real WTF there. The last person to access MSDN from this browser was "so and so", so it's a good bet that "so and so" is the one in front of the screen right now. However, it's not certain, so they'll have to prove who they are if they want to do something that requires an account.
-
It's a shame the offline version cannot update itself, well atleast mine couldn't.
