Feeds

Unhelpful Microsoft help denies helpless millions help

What does this button do?

Internet Security Threat Report 2014

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

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.

Beginner's guide to SSL certificates

More from The Register

next story
Netscape Navigator - the browser that started it all - turns 20
It was 20 years ago today, Marc Andreeesen taught the band to play
Sway: Microsoft's new Office app doesn't have an Undo function
Content aggregation, meet the workplace ... oh
Sign off my IT project or I’ll PHONE your MUM
Honestly, it’s a piece of piss
Return of the Jedi – Apache reclaims web server crown
.london, .hamburg and .公司 - that's .com in Chinese - storm the web server charts
NetWare sales revive in China thanks to that man Snowden
If it ain't Microsoft, it's in fashion behind the Great Firewall
Chrome 38's new HTML tag support makes fatties FIT and SKINNIER
First browser to protect networks' bandwith using official spec
Admins! Never mind POODLE, there're NEW OpenSSL bugs to splat
Four new patches for open-source crypto libraries
prev story

Whitepapers

Forging a new future with identity relationship management
Learn about ForgeRock's next generation IRM platform and how it is designed to empower CEOS's and enterprises to engage with consumers.
Why cloud backup?
Combining the latest advancements in disk-based backup with secure, integrated, cloud technologies offer organizations fast and assured recovery of their critical enterprise data.
Win a year’s supply of chocolate
There is no techie angle to this competition so we're not going to pretend there is, but everyone loves chocolate so who cares.
High Performance for All
While HPC is not new, it has traditionally been seen as a specialist area – is it now geared up to meet more mainstream requirements?
Intelligent flash storage arrays
Tegile Intelligent Storage Arrays with IntelliFlash helps IT boost storage utilization and effciency while delivering unmatched storage savings and performance.