Hacker News Reader

Comment by snakeanus | Hacker News Reader

I feel disgusted after reading this. I wonder how many people applied the advices given by the original article because they made the bad decision to trust the official documentation by MS.

View on HN

Oh, come on: whatever Microsoft's faults might be they have a very long track record, stretching back decades, of providing overall high quality documentation for developers.

Yes, there are errors. Yes, sometimes there is deeply misguided advice. But, on the whole, MSDN and its ilk has helped me far more often than it's hurt me.

Key point: compared with much other vendor and OSS documentation, Microsoft are absolutely streets ahead.

Most of the documentation is boilerplate. There's very little real content now and most of it is filler.

Here's an example of a new API they added recently (the first one I thought of): https://msdn.microsoft.com/en-us/library/windows/desktop/mt5...

It says things like this:

> Indicates that the data for the file should be obtained from a WIM file. On access, data is transparently extracted from the WIM file and provided to applications. If the file contents are modified, data is transparently decompressed and the file is restored to the same physical form it had if this API were not used.

This is "boilerplate" and "very little content" to you? What are you thinking of?

To be fair Win32 isn't terrible. Have you looked at the .Net docs?

http://imgur.com/a/iK4uG

I haven't to be honest, but at the same time I'm not sure what you expect to see as the summary here. Is there anything profound to say about two overloads that differ by an extra "millisecond" parameter?

You need to click on the overload of this method that you are interested in. This is just the top level "where do you want to go?" document.

It's not. There's a content about 11 screens down, not that you'd find it easily.

Again, GP just stated that these are local links, links to anchors on that very same page, explaining the overloads.

Are there too many? For this class, maybe. It's at least potentially worth discussing it. But the way the navigation works isn't "just scroll until something seems to fit".

If I could down vote this twice I would. I can't tell you how much I've been on the phone with MS support to try and do basic things with their software but can't because a.) the only existing documentation is wrong or b.) there's no documentation. My company pays MS a lot of money to not be able to do basic things with its software.

MSDN really? I never use it. I always end up someplace else. The information is there somewhere, maybe. I don't use other vendors much to know but MSDN sucks for me majorly. Not a microsoft fan generally though so maybe too much pain this past 30 years for an objective view.

The last time I really had to deal with a bad MSDN article was probably 2003 working on an ASP/VBScript application that used MSXML. I was in my last year of High School, working for a local bank doing things that were certainly above my pay grade, with extremely minimal support, in my glory days.

I remember getting 90% of the way through writing my application in VBScript and finding a piece of documentation about some XSD thing that I really needed to do to complete the tool, and that lots of people were reporting my similar issue, the support reply basically said, "get f'ed," this function works in JScript implementation of MSXML but not in VBScript.

Sorry! Hope you have hundreds of spare hours to learn a new language and port over your entire codebase, because we're not fixing it.

Every time since that I can remember I have ever referred to MSDN, I have found one post with my question, asked in clear terms that I could reach from a google search... posted four years ago, with one or more replies that are almost always very obviously wrong, from MS Certified Partner(TM).

Maybe some of their documentation is great! I have not had the fortune to encounter it.

While many open source projects have great documentation, and many others do not, the difference tends to be that if your Open Source project has bad documentation, or features that just plain don't work, you are free to read the source code and fix it yourself!

Reply on news.ycombinator.com