Original URL: https://www.theregister.com/2007/03/08/msdn_gloom/
Unhelpful Microsoft help denies helpless millions help
What does this button do?
Posted in Columnists, 8th March 2007 15:16 GMT
Stob 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, new MSDN2, presumably so-called because it takes twice as long to display (Really. MSDN-1 takes 8-10 seconds here, versus 15-20 seconds for MSDN2, depending on time of day. Try it. Or better yet, choose your own function for the experiment, in case some MS wiseacre does a little spot of optimisation)
I first came upon this entry about 10 years ago or more, when I noticed that an MDI app that I had made used to flicker like mad while the code was opening up a shed load of database tables. I wanted to stop this. Searching MSDN on CD-ROM, I eventually stumbled on LockWindowUpdate, which from the cited function description looked like the business. So I wrapped up my update code in an exception-protected pair of calls, and congratulated myself on an excellent spot in the face of the sprawling hugeness of the Windows API.
I have previously mentioned Raymond Chen's blog. I recently came across this series of one, two, three, four and five articles, but the passage that secured my full attention is this bit from number four:
People see the "the window you lock won't be able to redraw itself" behavior of LockWindowUpdate and use it as a sort of lazy version of the WM_SETREDRAW message. Though sending the WM_SETREDRAW message really isn't that much harder than calling LockWindowUpdate. It's 20 more characters of typing, half that if you use the SetWindowRedraw macro in <windowsx.h>.
Gah?
So, just to get this straight, people who call LockWindowUpdate are lazy, are they Mr Chen? That would be as opposed to people who are so lazy that, for example, they don't bother to document their own API, eh Mr Chen?
Mr Chen's articles say, believably, that LockWindowUpdate is exclusively intended for dragging operations. You lock somebody else's window, you draw your dragged stuff on top of it, it can't mess up what you draw because you've locked it. There. I just accomplished in 25 odd words what MSDN fails to say in 10 times as many – ie to describe the intent of the function.
Because there is absolutely no way you can get from the information supplied in the MSDN to the intended purpose of this function, as explained by Mr Chen. You stand no chance whatsoever. The reference I gave you above makes no mention at all of this dragging stuff: not a scintilla of a sniff of a soupcon of a suggestion. Absolutely zip. If you relied on MSDN's entry of this function, you would never, ever use it correctly. You are dead meat.
Ok, so the function reference page is pants. What about MSDN's overview material? Mr Chen mocks those who have not read it ("there's more to documentation than dry function descriptions, people!"), but since there's no direct link to it from the function page, why would you find it? (And why isn't there a direct link? Easily generated automatically by a suitable program, I offer this to Microsoft as a free idea to improve MSDN at one bound, and generously undertake not to apply for a software patent for it)
By my reckoning, a minimum of three lucky clicks – at 20 slow seconds a shot on drive-time MSDN2, remember – will bring you to this page. What a disappointment when you get there. Instead of explaining how you, the punter, can use the function, it mostly discusses how "the system" (ie Windows itself) draws a "tracking rectangle". This is probably an excellent example if you happen to use Microsoft's jargon for "tracking rectangles" (I think from Mr Chen's discussion it means the XORed boundary line you used to get when dragging windows back in the days before they painted content on the move; a little picture would be good here). And, of course, if you happen to have the relevant Windows source code to hand.
As it is, I say the entry is more or less useless, although I admit, when you know what it is trying to say, it does corroborate Mr Chen's explanation of the function's purpose.
I suppose it's possible Mr Chen was attempting a joke with this "lazy" business. He complains at the end of his series that his jokes have been misunderstood. Reading carefully through the sequence, I haven't found anything at all that I believed was a joke, so it is therefore feasible that this is what the "20 more characters of typing" stuff is intended to be. I have to tell him that "Hahaha! Look what I know that you don't know because we don't tell you," doesn't feel very funny when viewed from outside Microsoft.
In the follow-ups to his blog, many others have raised the points I make here. What does Mr Chen think? In an early reply, Mr C hands out defensive guff about
the tension between "descriptive" and "prescriptive" documentation
which would seem to imply that he supports the MSDN stew that we find. But then later on he distances himself haughtily:
It appears that everybody is under the impression that I approve of the documentation
Yes, I wonder why that is?
Mr Chen surely knows that MSDN's coverage of LockWindowUpdate is a load of horse poo. He is able to supply an intelligible description of how it is supposed to be used, and his opening salvo in the first article ("Poor misunderstood LockWindowUpdate") makes it clear that he is aware that almost nobody outside the charmed circle groks it. In the past, Mr Chen has occasionally taken pride in shooting down other Microsoftees when he thinks it is deserved. Why, then, does he hold his fire here?
How about this: because LockWindowUpdate is entirely typical of MSDN. The whole, bloated thing is jam-packed with function descriptions that tell you everything about the function except what you need to know, huge, dull, explaining-by-not-explaining articles extracted like rotten teeth from MSDN Magazine and its predecessor MSJ, and filled with bogus enthusiasm for, say, this month's approved way of interfacing to databases.
Then there are the dreadful, slow searches, compulsory in the CD-ROM only days, now happily alleviated by Google (What is it about Microsoft and indexed searchable text? They always seem to get it badly wrong: think Windows Search, think those old help file indexes that always needed rebuilding). And why the almost complete absence of pictures? This is, after all, supposed to be the documentation for a graphical operating system.
Think about the last time you needed to use an unfamiliar API. Did you first go to MSDN? Of course you did, and there you learned that LockWindowUpdate locks windows against update – or rather its equivalent about hosting the Microsoft scripting engine, or drawing in DirectX, or writing a device driver, or whatever.
So then you Googled everywhere else: websites like the The Code Project, newsgroups, non-Microsoft magazines, any raw source code drifting round the net. All the time praying: please let me not be the first, please let some genius have worked out what they are trying to say, please let me not be the poor bloody infantry.
Why is MSDN so terrible? I guess because it is always written against brand new releases of APIs by people who are too close, too inexperienced and/or too immersed in Microsoft culture to recognise the outside reader's needs. Once an article is written, it is essentially frozen; only to be revised to accommodate technical changes or inaccuracies, or dropped with discarded technology. Nobody is allowed (let alone encouraged) to poke around and say "Ooh look! That's terribly obscure. That could do with a rewrite"; a huge weight of bureaucracy and a culture of legal arse-covering forbids it.
And it has been terrible for a hell of a long time. LockWindowUpdate comes, I suppose, from the Petzold era of the late 1980s. Since then, we have had the rise and fall of C++ and COM, and now the current ascendancy of C# and .NET. All the while, the documentation style has remained the same: precise but not informative, looking inwards while pretending to look outwards. It is a triumph of medidocrity.
(Oh dear, I'm not sure that has come off. And I had such high hopes.)
Because it is possible to do large-scale documentation properly. The proof of this exists for you to see, and it is called the PHP Manual. Go there now, if you like, and look up a function. The one I chose was phpinfo, and – let's deal with the easy-to-measure, objective metrics first – it came up in about two to four seconds, varying according to time of day. But always in less than half the time of the quicker of the MSDNs.
As well as searching quickly (they use Google, of course), drawing the page quickly (it's PHP not .NET), and not using those awkward frames and vertical scrollbars that make a pig's ear out of every single MSDN page, you will notice one supreme, kicker feature.
The PHP people didn't write it.
At least, not all of it. The bottom of each page is filled with user comments. In addition to having the unfair advantage of understanding how to do good HTML layout and a fast scripting language, the PHP crowd has the non-arrogance to realise that it doesn't know everything, and provide a space for punter correction and improvement.
See how contributors compete to out-do each other in the usefulness of their donated snippets. Look! Look! My code has colour syntax highlighting!
And of course, as time has gone on, the PHPers have built up a mass of useful and pointed comment, which they can then incorporate into the proper documentation itself. Instead of decaying gracelessly, like MSDN articles, the PHP manual incorporates a wonderful virtuous circle.
PHP has emerged as a leader from a niche packed with both commercial alternatives (cold, cold, cold ColdFusion, Microsoft ASP/ASPX stuff, back-end Java) and superficially better-favoured open source rivals such as Python (cleverer, more elegant) and Perl (first, originally ubiquitous). PHP's wonderful documentation system must surely be a hefty factor in its success.
Meanwhile, back at Microsoft and LockWindowUpdate and Mr Chen's blog and all that, somebody mentioned the PHP system. Mr Chen, who apparently as a point of principle never, ever takes any criticism gracefully, gleefully made the online equivalent of a nurny-nurny nur nur noise and pointed to the recently-started MSDN-Wiki. Hurrah. It is indeed a train bringing light towards us from the end of the tunnel, but the nameplate on its smokestack is "Hope". (Did I really just write that? Cripes! Yuck!) Very late in the day, Microsoft is attempting to crib the PHP approach.
Of course, it may still fail. It will, I bet, suffer from all the usual Microsoftish sort of problems: too slow, too clumsy, you need a Hotmail "we track your IP address everywhere" account to use it. The temptation and pressure to edit even mildly unwelcome comments out of history will be terribly strong. I hope someone in Microsoft has the guts to resist. A similar system that was easing the wretchedness of Macromedia's Flash MX 2004 manual was abruptly castrated overnight, when a team of top censors went in and removed nearly all the posts, especially the ones that pointed up the incomprehensibility of the existing material.
But however things turn out, I'm afraid it is coming too late to save poor, bloody me. We're looking at making our stuff Vista-proof, and I have been nominated to put the new OS on my PC, and read up on the new security APIs. As Ren & Stimpy used to sing: Happy Happy Joy Joy Happy Happy Joy Joy.
This month's assignment
This month's assignment is to document phpinfo in the style of MSDN. For example, you might start something like this:
phpinfo produces a stream of HTML code tokens and text that can be parsed to deduce version numbers of system components...
®