It was one of those wonderful moments when a task that was, a moment ago, frustrating and nigh-impossible, suddenly became less daunting.

I’d been wrestling with PowerShell. We were checking and editing a PowerShell article for Simple Talk and I’d started the ritual of testing out the code and making sure that all the instructions worked. It is often difficult for the authors of articles to think themselves into the role of educated beginner in a technology, so someone usually has to check that instructions are graded and complete. As usual, I was voted by the editorial committee into the role.

My epiphany happened when I typed in
Get-Help Get-Command -examples
…and
Get-Help Get-Command -full
… and wondrous stuff spilled forth down the screen. Suddenly, I could make progress. Obviously, I had to type in the name of the particular cmdlet for which I wanted examples of use but, hey, I can cope with that.

It was beautifully written help, brief but to the point. With that, and a few simple examples of full PowerShell scripts, I was airborne. It made me think how unnecessary so much of the training and publication industry around Microsoft actually is. There is a huge industry that interprets the information that Microsoft provides and re-interprets it for mere mortals without otherwise adding much extra value. Even Microsoft itself has joined in the game. It gives us the information from the developers distorted by ‘chinese whispers’, rather than from the source. SQL Server Books-on-Line has always provided a rich harvest for the trainers. Everything is there, if you can find it, but has, in the past, been painfully structured, short on practical examples and often written in a style that refuses to compromise with the less brain-bound reader in any way. Inevitably, an industry has developed to interpret the occasionally strangulated text of some of the MSDN information into reasonable, simple English.

There are, within Microsoft, people who really understand their products and can communicate them well. Whoever provided the terse but valuable help text for PowerShell was, surely, a developer talking direct to other developers. It has always been a difficult struggle for any software provider such as Microsoft to pitch it right: to make sure that the key people have the time to trasmit their knowledge and understanding to others. This is a difficult balancing act to perform, since few of the creative developers are natural communicators. But when they are, then we all gain.

With any software product of any complexity, the job isn’t finished until its use is made crystal-clear to the end-user. It is not a peripheral task. The people who developed the system are always best placed to write about it. This is why books such as Brian Kernighan and Dennis Ritchie’s “The C Programming Language” (Dennis Ritchie wrote C), and Brian Kernighan and P. J. Plauger, “The Elements of Programming Style” (Kernighan wrote AWK and a lot else besides) remain classics of the art of explaining complex technology in a simple approachable way.

What do you think? Is it better for developers to stick to coding and leave the wider aspects of communicating with the users of their applications entirely to others; or is it better to encourage them to participate more in explaining how their applications work?

Cheers,

Tony