Unhelpful Microsoft help denies helpless millions help

What does this button do?

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


Sponsored: Minds Mastering Machines - Call for papers now open

Biting the hand that feeds IT © 1998–2018