Unhelpful Microsoft help denies helpless millions help

What does this button do?

Secure remote control for conventional and virtual desktops

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 onetwothree,  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>.


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.

Boost IT visibility and business value

More from The Register

next story
Munich considers dumping Linux for ... GULP ... Windows!
Give a penguinista a hug, the Outlook's not good for open source's poster child
The Return of BSOD: Does ANYONE trust Microsoft patches?
Sysadmins, you're either fighting fires or seen as incompetents now
Intel's Raspberry Pi rival Galileo can now run Windows
Behold the Internet of Things. Wintel Things
Microsoft cries UNINSTALL in the wake of Blue Screens of Death™
Cache crash causes contained choloric calamity
Time to move away from Windows 7 ... whoa, whoa, who said anything about Windows 8?
Start migrating now to avoid another XPocalypse – Gartner
Eat up Martha! Microsoft slings handwriting recog into OneNote on Android
Freehand input on non-Windows kit for the first time
You'll find Yoda at the back of every IT conference
The piss always taking is he. Bastard the.
prev story


Endpoint data privacy in the cloud is easier than you think
Innovations in encryption and storage resolve issues of data privacy and key requirements for companies to look for in a solution.
Implementing global e-invoicing with guaranteed legal certainty
Explaining the role local tax compliance plays in successful supply chain management and e-business and how leading global brands are addressing this.
Top 8 considerations to enable and simplify mobility
In this whitepaper learn how to successfully add mobile capabilities simply and cost effectively.
Solving today's distributed Big Data backup challenges
Enable IT efficiency and allow a firm to access and reuse corporate information for competitive advantage, ultimately changing business outcomes.
Reg Reader Research: SaaS based Email and Office Productivity Tools
Read this Reg reader report which provides advice and guidance for SMBs towards the use of SaaS based email and Office productivity tools.