In lecture today, someone noted that they'd found a mistake in some of Microsoft's documentation. The professor then said something along these lines: "Does that really surprise you? Microsoft has quite a reputation for bad documentation. And bad software." That last jab reveals the depth of the professor's bias (attacking on an issue unrelated to the question). But I wonder if I'm just biased the other way. I've generally found MSDN to be pretty good, but am I wrong? Anyone else here have feelings one way or the other on MSDN compared to other technical documentation for programmers?

heh. My professor (he teaches operating systems) hates Microsoft with a passion. For fun on the last project I handed in all my references were from MSDN. I personally love their documentation for C#. The only documentation that kind of sucks is there coverage of winsock which gives inadequate examples for beginners.

I think their documentation is very good, or maybe I just got used to the lack of documentation and examples from some open source and third party libraries.

I've never had a problem with their documentation, infact i think i actually enjoy it. I just make sure to always use google to find what i'm looking for, rather than the MSDN search.

Universities are Unix shops. Some bias is to be expected. You'll get similarly biased opinions asking a bunch of game developers about Unix.

MSDN's not bad. Their non-reference documentation is usually pretty well done. Reference documentation is well-organized, but can be overly terse or misleading.

Quote: Original post by Kwizatz
I think their documentation is very good, or maybe I just got used to the lack of documentation and examples from some open source and third party libraries.

I'll go along with that. Some of the open-source projects have built up a very good culture of documentation (see PHP and MySQL), while some quite popular open source projects have horrendously bad/lacking documentation.

Actually, I can't think of a popular programmer-targeted open source project with bad documentation off the top of my head, probably because I quickly gave up on those ones :-)

Your professor is showing a bias.




The documentation is quite good, especially relative to most other documentation sources. The details of the functions and technologies are reliable.

Back before 2002 it had problems mainly because the Visual C++ compiler was pre-standard. It documented what the compiler actually did rather than what the language specified. In that respect it was both good (accurate for their compiler) and bad (contrary to the actual language).

Many of the examples tended to have a lot of problems, but over the past few years Microsoft has made an effort to clean those up. There are still occasional errors, but they are less common and usually less severe than similar example errors you find online.



As for his bad software statement, it was uncalled for. If he wanted to cite a specific product has having specific problems that would be appropriate. Every major application has bugs, regardless of who wrote it. Claiming that there is bad software from a company which maintains thousands of products is just stupid.

I find about 98% of MSDN documentation to be perfectly adequate. It's not great, especially the quality of the code samples, but the code samples aren't intended to be directly pluggable into a production system. On the other hand, that remaining 2% of the time can really, really ruin your day. For example, the MSDN documentation for localization functions in the CRT. The really important detail of what the locale ids correspond to which locale is buried to the point where reasonably intelligent people familiar with MSDN can take more than a couple days before finding it. And this detail is a basic prerequisite for using any other function in the whole subsystem.

I found MSDN to be generally good, as long as your expectation is for a reference, not a tutorial.

I find their tutorials to be a mixed bag and rely far to much on various bits of common code and/or frameworks instead of being stand-alone. This makes it hard to translate into the common code and/or framework I'm actually using. It also makes it hard to get samples up and running without installing and building the world.

My biggest beef is that they seem to have all eleventy-million different versions of Windows SE as seperate entries and they almost invariably show up in the search lists before the base Windows version. I wish they would collapse them into a single entry with notes on platform differences as needed. Similarly, it can be extraordinarily difficult to get at a native API that happens to have the same name as a managed API.

MSDN is an invaluable reference source. Don't expect to use it as a step-by-step tutorial because that's not its purpose. I have often found it to be an absolute life saver and it's saved my ass on many occasions.

One thing that needs to be gutted and redone is those official XNA tutorials. They stink, quite frankly; bad quality, uncommented spaghetti code which is hardwired for use in that tutorial and that tutorial only.

P.S.: don't take anything your professor says with regards to industry because chances are they have a) no knowledge of their own and rely on industrial panels or b) their knowledge is out of date by about ten thousand years. And, as Sneftel says, most Universities are Unix shops for the most part.