According to a recent revelation from a colleague, freshly returned from the bi-annual International Sock Summit, you can now buy sock knitting needles made from carbon fibre; the same stuff they used to make the Stealth Bomber. Why? Maybe it's so you can knit socks that can't be detected by enemy radar? Or it's so they won't break from the rapid heat generation and extreme strain during a sock-knitting speed contest (and, yes, there are such things - see this site if you don't believe me).
Probably it's really all about status symbols and consumer aspiration. I guess it follows along from similar seemingly inappropriate material choices such as using airplane-grade aluminium for the cases of laptops (perhaps they are designed to fly when you toss them out of a window in exasperation at some software glitch). Or the protective sleeve for my mobile phone that is made out of ultra-tough scratch-resistant polyvinylsomethingorother, and is so slippery that the phone slides off my desk at least twice a day. Good thing, I suppose, that it has an ultra-tough protective sleeve.
But cursory examination of modern consumer goods soon reveals that material choice is something manufacturers never really got the hang of. You only have to walk past our stainless steel microwave oven and the shiny front panel needs cleaning again. And the people who designed our electric kettle decided, for some reason, that the best material for the little lever that connects the switch to the internal gubbins is some kind of thin and very fragile plastic. We're on our third replaced-under-guarantee one already...
So it's only right that I should strive to avoid poor material choice in my day job of writing guidance for software developers, designers, and administrators. Trouble is, it's a lot harder than choosing between stainless steel and vitreous enamel, or between metal and plastic; and it's far more difficult to do empirical testing of the finished product. They might have machines that turn a switch on and off ten million times to see if it breaks, but I've never been able to find a mechanized device for testing written guidance to destruction.
Yes, I know that modern proofing tools such as Word do clever grammar, spelling, and sentence structure checks. In fact, Word just red-wiggleyd the word "gubbins" in an earlier paragraph. Yet it's a proper word (at least, here in England), as you can see from Free Dictionary (or, for a much more interesting definition, check out Uncyclopedia).
The point is that getting the grammar, spelling, and sentence structure right is useful (it saves my editor tons of work), but it doesn't actually prove anything about the content in terms of material choice. It might be syntactically correct, wonderfully phrased, and rise from the page with all the grace and beauty of a Rachmaninov Piano Concerto. But is what's in there actually any use? Are there bits inside that will break as soon as you start to use it? Or will the shine go off it completely when you get to the end of the introductory paragraph (rather like this blog, I guess)? And will I suddenly get a ton of emails demanding a replacement under guarantee?
For example, we recently decided we needed a chapter for some Azure guidance that describes the increasingly wide range of services and features available in Windows Azure and SQL Azure (and Windows Azure AppFabric and Windows Server AppFabric, which are different things). I reckon somebody told the Azure dev team because, as fast as I wrote stuff, they added more features. It was like trying to finish a bowl of soup while sitting outside a cafe in a rainstorm. And then, as soon as I finished one bit, they changed the feature again. Obviously I've done something in the past to annoy them and they're getting their own back.
But that's just the point. How do I test my guidance other than re-reading it every day and re-checking all the sources? The original data came from dozens of different sources, and none of them will be helpful enough to drop me a note when they change something. They expect me to figure out what's happening by monitoring hundreds of different sources all the time. And, of course, once we press the big red "print" button and churn out ten thousand beautifully designed and bound hard copies it's too late to do anything about it.
The answer, as I've suggested in previous posts, is to simply provide semi-vague descriptions of the features and links to the original resources - just as a developer links to some assembly they want to use in their code. As long as the interface (or, in our case, the URL) stays the same it will "just work". But all I'm doing is making the reader do the work of chasing round the myriad resources, and deciphering and distilling the knowledge they need from them. It's not really a solution.
A typical example is with Azure Service Bus (a topic dutifully discoursed in a recent post). It used to be just a way of doing messaging, queuing, and eventing through firewalls and NAT routers. Now it's a fully-fledged communication and service access mechanism to which you can add topics, rules, discovery, and more. And they still haven't finished adding things. It almost seems as though soon you'll start building your application with Service Bus and then bolt things onto the edges afterwards.
Ah, but maybe this is the answer to my guidance-material-appropriateness problem. I just need to build an application that runs in the cloud and uses Service Bus to connect directly to all of the guidance resources. It can use discovery to find new related material; topics, rules, and actions to select the appropriate parts; a worker role to assemble these into a finished guidance document; queues to store the updated material until I'm ready to use it; and secure messaging to send it directly to my laptop through Azure Connect.
When the source material changes, it would use Service Bus event subscriptions to notify changes, and automatically rebuild the content with the new material. Of course, that doesn't help with the printed books, but if we could switch everyone to using tablets and electronic reader devices we could pipe the new content to them automatically once they subscribe to the Service Bus events.
Unfortunately, however, even this level of technological capability and comprehensive interconnectedness can't resolve the core issue. For a start, there's no way that it can understand the actual contents, or comprehend the needs of the reader. I've fallen into the trap of being distracted by a great new technology, and tried to bend it to meet my requirements when it's obviously not going to solve the original problem. I lost track of the scenario whilst wallowing in the depths of the technical capabilities.
And that's just it. Technical information about a specific product or feature may not help you to understand how you map it to your own infrastructure and requirements, or even if it's actually a suitable technology. Every system is different, and so the only real-world solution is to discover the scenario and then see if the product actually maps to that scenario. It may be that there are better ways to implement the solution; or different technologies that provide a better fit.
So what we do here at p&p is create guidance that looks outside of the product documentation to map the vast range of products available to the requirement of ordinary users. Given scenarios discovered from wide-ranging user feedback, we attempt to show how you apply the most appropriate technology, and do so in the most efficient way. We look for common patterns and discover the ways that you can follow good practice when applying the technology solutions.
Maybe that's why we're called "patterns & practices"...