Feeds

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

®

Providing a secure and efficient Helpdesk

More from The Register

next story
UNIX greybeards threaten Debian fork over systemd plan
'Veteran Unix Admins' fear desktop emphasis is betraying open source
Netscape Navigator - the browser that started it all - turns 20
It was 20 years ago today, Marc Andreeesen taught the band to play
Redmond top man Satya Nadella: 'Microsoft LOVES Linux'
Open-source 'love' fairly runneth over at cloud event
Google+ goes TITSUP. But WHO knew? How long? Anyone ... Hello ...
Wobbly Gmail, Contacts, Calendar on the other hand ...
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
Torvalds CONFESSES: 'I'm pretty good at alienating devs'
Admits to 'a metric ****load' of mistakes during work with Linux collaborators
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 and how to choose the right cloud vendor
The benefits of cloud-based storage in your processes. Eliminate onsite, disk-based backup and archiving in favor of cloud-based data protection.
Three 1TB solid state scorchers up for grabs
Big SSDs can be expensive but think big and think free because you could be the lucky winner of one of three 1TB Samsung SSD 840 EVO drives that we’re giving away worth over £300 apiece.
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.
Security for virtualized datacentres
Legacy security solutions are inefficient due to the architectural differences between physical and virtual environments.