Feeds

Unhelpful Microsoft help denies helpless millions help

What does this button do?

Seven Steps to Software Security

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

®

Reducing security risks from open source software

More from The Register

next story
HIDDEN packet sniffer spy tech in MILLIONS of iPhones, iPads – expert
Don't panic though – Apple's backdoor is not wide open to all, guru tells us
Do YOU work at Microsoft? Um. Are you SURE about that?
Nokia and marketing types first to get the bullet, says report
Microsoft takes on Chromebook with low-cost Windows laptops
Redmond's chief salesman: We're taking 'hard' decisions
Cheer up, Nokia fans. It can start making mobes again in 18 months
The real winner of the Nokia sale is *drumroll* ... Nokia
EU dons gloves, pokes Google's deals with Android mobe makers
El Reg cops a squint at investigatory letters
Chrome browser has been DRAINING PC batteries for YEARS
Google is only now fixing ancient, energy-sapping bug
Big Blue Apple: IBM to sell iPads, iPhones to enterprises
iOS/2 gear loaded with apps for big biz ... uh oh BlackBerry
prev story

Whitepapers

Reducing security risks from open source software
Follow a few strategies and your organization can gain the full benefits of open source and the cloud without compromising the security of your applications.
Consolidation: The Foundation for IT Business Transformation
In this whitepaper learn how effective consolidation of IT and business resources can enable multiple, meaningful business benefits.
Application security programs and practises
Follow a few strategies and your organization can gain the full benefits of open source and the cloud without compromising the security of your applications.
Boost IT visibility and business value
How building a great service catalog relieves pressure points and demonstrates the value of IT service management.
Consolidation: the foundation for IT and business transformation
In this whitepaper learn how effective consolidation of IT and business resources can enable multiple, meaningful business benefits.