Unhelpful Microsoft help denies helpless millions help

What does this button do?

Secure remote control for conventional and virtual desktops

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


Secure remote control for conventional and virtual desktops

More from The Register

next story
Why has the web gone to hell? Market chaos and HUMAN NATURE
Tim Berners-Lee isn't happy, but we should be
Microsoft boots 1,500 dodgy apps from the Windows Store
DEVELOPERS! DEVELOPERS! DEVELOPERS! Naughty, misleading developers!
'Stop dissing Google or quit': OK, I quit, says Code Club co-founder
And now a message from our sponsors: 'STFU or else'
Apple promises to lift Curse of the Drained iPhone 5 Battery
Have you tried turning it off and...? Never mind, here's a replacement
Linux turns 23 and Linus Torvalds celebrates as only he can
No, not with swearing, but by controlling the release cycle
Scratched PC-dispatch patch patched, hatched in batch rematch
Windows security update fixed after triggering blue screens (and screams) of death
This is how I set about making a fortune with my own startup
Would you leave your well-paid job to chase your dream?
prev story


Top 10 endpoint backup mistakes
Avoid the ten endpoint backup mistakes to ensure that your critical corporate data is protected and end user productivity is improved.
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.
Backing up distributed data
Eliminating the redundant use of bandwidth and storage capacity and application consolidation in the modern data center.
The essential guide to IT transformation
ServiceNow discusses three IT transformations that can help CIOs automate IT services to transform IT and the enterprise
Next gen security for virtualised datacentres
Legacy security solutions are inefficient due to the architectural differences between physical and virtual environments.