Here is a little contest, to which all fellow Windows programmers are invited. What is the API function LockWindowUpdate for? How might you use it? You are definitely allowed, nay encouraged, to use the official Microsoft documentation. Here is the function description on MSDN, and here is the same documentation on the upgraded …
As a developer whose main compiled coding language is VB and main web coding language is PHP, I (unfortunately for my sanity when trying to use MSDN) don't think you could have got this any more painfully accurate!
You don't understand
MSDN is a gift to you. You should be honored to have access of any kind.
Besides which, why are you writing your own GUI code? Isn't Microsoft's good enough for you?
Yes and No
Although i have mainly developed using Microsoft technologies in the past, I have recently had to pick up a PHP based project half way through. Initially I was not looking forward to this after some bad experiences 6 or 7 years ago, when in my opinion the available documentation for PHP was next to unusable compared to the windows script 5.6 docs. however now that i mainly use .net the PHP docs have an excellent clarity in both what and how functionX does what ever it does.
However i do find the comments especially on some of the more well known functions to be wiki like in the amount of conjecture and opinion. perhaps a simple color coding of the posts and light handed moderation could help, e.g. a different colours for a recommendation, comment, and elaboration on an entry and an editorial process to elevate a comment to a recommendation/elaboration....
Given the breadth and depth of MSDN im not so sure a similar system would work, although a UI overhaul would deffinatly help
I dont mean an insane web 2.0 httprequest gibbering, needlessly client side scripted RSS spewing mock up of a desktop app
REMEMBER KIDS, just because you might have a broad band connection WWW still stands for World Wide Wait
yes, we should really thank Microsoft...
"MSDN is a gift to you. You should be honored to have access of any kind."
Let's see who benefits most from this: after all, the more applications are written for their OS, the "better" it looks. Microsoft derives huge revenues from its operations, and if there were few third-party apps produced, would it have such a large user base?
I would say that, contrary to the above comment, Microsoft is almost totally dependent for its market position on the efforts of third-party producers, and it makes sound business sense to assist them in every way possible, including decent software development information and tools.
So it's not an honour: the development community is keeping Microsoft in business.
Why should they?
Why should Microsoft even consider writing good documentation?
Projects aren't started on Microsoft's platforms because people deliberately evaluate different alternatives, but just because it's the best thing they know.
The last programming I did for MS-anything was a program in VBDOS 1.0, to operate a piece of equipment for testing electronic controllers for fancy gas boilers as they came off the production line. This was running on a '486 PC, with 1MB RAM and no network.
The more articles I see like this, the gladder I get that I'm working in a Microsoft-free environment -- and the odder I find it that people are *still* using Windows as a platform, given that there are now serious alternatives are out there.
Bam! Right on the money. This has been the case for, well, FOREVER with Microsoft. They've always been reticent about providing any more that the minimum descriptive documentation because they view outside developers with a jaundiced eye. Heck, we're their competition. Documentation to them is just an evil necessity.
Just remember this, the development tools side of Microsoft will AWLAYS play second banana to the OS and applications side of MS, and decisions will be forced upon them no matter how ill conceived. This isn't guessing, it's just history.
MSDN2 : Server is too busy
While the author recorded MSDN-2to take 15-20 seconds to load, I simply get
"Server is too busy"
Some MS wiseacre DID a little spot of optimisation, indeed.
Slamming Raymond Chen is wrong
Raymond Chen is a programmer at Microsoft that posts out of his own good will, sharing his knowledge and experience working in Windows.
He IS NOT a diplomat, he is a programmer just like us and he speaks like the person in the next cubicle. It is a personal blog and the benefits far outweigh the occasional 'hurt feelings' you might get, and frankly, that's all that this pseudo-article is about - you don't really care about LockWindowsUpdate.
There is nothing that positive that can come out of glorified flames like this article except turning off good people like Raymond out of posting and providing helpful hint.
People like us learned Windows programming from Charlez Petzold, we know what WM_SETREDRAW is for, and we work with samples and not just by finding random functions in the MSDN index and guessing what they're for.
The samples for windows programming are in the Plateform SDK, they are not in the pages of the documentation of the API. It looks like you feel stupid and angry because you used LockWindowsUpdate in the past the wrong way... that's you, it's not a global problem. If you don't know what a 'tracking rectangle' is you probably have never made any effort to learn programming Windows and read the doc.
When you come off your little anger about the word 'lazy', lookup the QuicktimeAPI, OS X, man pages, etc, and you'll pretty much never find a complete discussion you are calling out of here. One page of reference documentation can't make a you a learn how everything fits together.
The only thing you're working up here is not better documentation, but rather cutting off the bridges of discussion as people become too afraid to be humiliated in public to talk.
Perhaps you'd just prefer everyone just shuts up and only read press releases and official statements.
Wide user base because of numerous 3rd party apps?
Quoting a couple of other comments:
"if there were few third-party apps produced, would it have such a large user base?"
"Projects aren't started on Microsoft's platforms because people deliberately evaluate different alternatives, but just because it's the best thing they know."
I disagree on both points.
The large Windows user base has nothing to do with the number of 3rd party applications available on the market. It has averything to do with Windows being forced down a customer's throat when they buy a new branded PC (as opposed to building it themselves). Many people don't even know that Windows isn't actually a part of the PC and that there are alternatives. Back in 2003 Dell France was even billing their customers (individuals, not businesses) 700 euros (that's about £450 or $900) to *remove* Windows and other bundled software.
Secondly, projects are not started on Microsoft platforms because "it's the best thing they know", but because it is the O/S with the largest user base and therefore opening the largest market.
Ahhh! I thought I was the only one. I was working on a problem with Named Pipes (not my code) trying to figure out why there seemed no concurrency. The documentation was pretty specific and to the point, replete with examples (all bad). Apparrently, they were like sockets. Accept a connection, spawn a thread to handle it, wait for another connection.
Eventually, I found the single sentence in all of the documentation that was really relevant. One connection per thread. The number of simultaneous threads waiting for a connection governed the level of concurrency. Shift a few lines of code around, and *voila*! Actual concurrency. Add a few more lines, and *viola*, now it's scalable.
But that is the sad tale with Microsoft's documentation and sample code. When it actually does work (seldom), it's usually a bit dodgy. One is forced to ask oneself, "Do they ever actually TEST any of this stuff?"
Ah, it takes me back to the old days, when a co-worker was trying on ASP for size (it was new, then). He popped by my cube, handed me a thick manual, and asked me to explain it to him (being CGI from the old school). Having read the legalese and sifted through the garbage, I told him what he needed to know. That was the scene of one of my best quotes. In response to, "Why didn't they just SAY THAT?", I answered, "Are you kidding? This book was written by some of the best minds at Microsoft. It's practically gibberish."
Putting Pressure on Microsoft
There are only two things that I have encountered in my career that have truly annoyed me. One is MSDN, and the other is Numerical Recipes in C. Both are fantastic examples of the way NOT to do things.
Personally, I find it shocking that a company with the resources and clout of Microsoft cannot produce good quality documentation for it's APIs.
Indeed, I suspect that most of the bad-feeling that Microsoft gets from the software engineering community is as a direct result of MSDN, and that an improvement in the developer documentation would do the company's PR image a world of good.
Failing that, I think that developers should think seriously about lobbying, or otherwise putting pressure on Microsoft to improve the situation.
I know writing to your local MP to complain about some documentation sounds a little silly, but if nothing else will work, why not give it a try?
It wasn't always this way...
Back when I was asked to build a help-desk system in VBA for Access (versions 2.0 and later 7), the F1 key was my friend - heck, you could learn everything you needed (at least I did), with cut-n-paste examples that actually made some sense, just from F1 & a simple search. Never bought a book -- never needed to. Starting with Access 97, things went downhill... and fast... and never recovered.
It sucks that over a decade ago, MicroSoft actually knew how to "do it right" and b0rked it up so bad in the name of "progress." Sheesh.
Roger "Merch" Merchberger
Made my day
How funny. What a way to turn a pretty ordinary, basic day into an overwhelmingly joyful day.
Not Only That But..
An associate referred me to your article with the comment
"Verity Bots is A Goddess" After reading it I replied
"We got anything better than goddess? Shorter hours, better wages? St. Swithin's day off with pay?"
As a professional in Knowledge Management, I'd like to add some remarks on *how* lousy documentation comes into being.
Not to defend Mr. Chen. I looked over his contributions and he is being a snot. This is a function of allowing programmers who actually sit in the development meetings to write/publish anything whatever. They are under the delusion that everyone knows what they think they know. (The gap between what they think they know and what is actually going on would make the grand canyon look like a hole in your sock).
Having met, worked with, under, and, finally, over the Mr. Chens of this world, I have also noticed that they are inordinatly fond of the notion of "intuitive"--going so far as to coin linguistic abominations such as "unintuitive" to describe things that they don't understand.
Anyway back to documentation creation--If a company has tech pubs departmet, team, group, coven, or whatever collective noun applies, a writer/editor is given the unenviable task of prying information out of the likes of Mr. Chen (Actually, its not so much getting them to tell you things. Its getting them to stop, before they explain all the way back to the phlogisten theory of light.) After a while the writer/editor applies various forms of torture to the raw information (including the removal of material the source expert think is humorous) and comes up with a variety of documents to support working with the API, including description, purpose, examples of use, and associated error codes and what to do about them. In addition the writer/editor does a little testing, checks with SQA to make sure that information is reasonably sound.
Someone quite senior to Mr Chen in his deparment reviews the document. And realizes that by letting application programmers run amuck at that level of the underlying code will create opportunites galore to crash the system, create security hazards, compromise patents, open legal liability, and generally bring about the end of civilization as we know it. But they have to expose the API otherwise no one out there will make applications they can appropriate for a 10th of the cost it would cost to develop them in-house.
So what to do? Simple, send back the nice documentation with a curt note to remove all references to Purpose, Use and most of the Examples.
Thus do the Mr. Chens serenely (and delusionally) beleive that the API is both intuitive and well-documented; the API is made safe for democracy; and Technical Publications learns to keep extremly meticulous records about who told them to do what and when because they keep getting blamed by Tout Le Monde for documentation that doesn't tell anyone anything.
Excuse me, now I must go and see to it that the "Problem Resolution" sections in a chapter on Error Messages are deleted.