Random Disconnected Diatribes of a p&p Documentation Engineer
I suppose it just shows how poor my business skills are. If I ran a hugely successful business directory company called "Yellow Pages" and wanted to extend it to the web, I'd have kept the name and made the web pages yellow. Instead, they changed the name to "Yell". I guess it works to some extent in that it's a verb so you can "Yell for a plumber", in the same way as you might Google or Bing one. But why, at a cost supposedly running into six figures, have they just decided to change the name again?
According to the newspaper, the new name is "hibu". I suppose I should applaud the fact that, in line with our own style guidance here at Microsoft, there is no unnecessary capital letter. But I can't see how it will work in relation finding a business in their directory - I suspect that few people will instinctively "hibu a plumber". The only reference I can find to the word is the name of the Norwegian college Hogskolen i Buskerud (Buskerud University College) or "HiBu". And they do manage to include some capital letters.
It's a bit like the weird name change that the mobile phone companies T-Mobile and Orange underwent after their amalgamation into one. The choice of the name "Everything Everywhere" has already been described as silly by no less than their chairman Stephane Richard. Meanwhile I confirmed that you can't buy a tin of baked beans from them, and your phone probably won't work on the Moon, so the name obviously contravenes some regulation or other.
Of course, the problem is finding a name that isn't a rude word in any language, and for which you can register an Internet domain. A colleague of mine owns a company whose name contains only a meaningless string of lower-case letters. Perhaps he chose it by entering letters at random into one of those web sites where you buy domain names until it came up with an available .com domain. Maybe we'll need to get used to company names such as "hwudniq", "clxystwm", and "odsengto" (all of which are, at the time of writing, still available).
But coming back to "hibu", it seems that I just don't appreciate the intricacies of modern marketing. The company declared that the new name is "short, easy to pronounce (though they had to include a note to say it's pronounced "high-boo"), edgy, and innovative". The CEO Mike Pocock even reminded people that names such as "Apple", "Google", and "Yahoo!" don't have any real meaning as words, and were unknown years ago. Well so was "Microsoft", but I can't see that Steve Ballmer will suddenly decide to swap it for one of the currently available names I mentioned earlier.
And I reckon Adam and Eve would have something to say about "Apple" not having any real meaning...
Talking to an acquaintance over email the other day, I was taken aback when he asked me when I'd exchanged my old car for a new one. As I hadn't, I asked what had prompted this inquiry. He lives at the other end of the country and hasn't ever been to my house, but he'd happened to wander virtually down our street on Google Street View (he knows my address) and seen a visitor's car parked on my driveway. So I thought it would be interesting to ask what else he could discover about my house and lifestyle, in particular from a security and privacy point of view.
A couple of days later the results were in. Google maps confirmed that I have a fishpond in the garden which might contain valuable fish, and a conservatory at the back so there is likely to be a vulnerable patio door; which is not easily visible from the road or from other houses. There are trees next to our house that could provide useful cover, while the wooden front and back doors would probably not take a huge amount of effort to force open.
As well as a large well-maintained garden, there's also a garage that's likely to house valuable tools and garden equipment. The patio furniture also looks as though it stays outside all the time. And we're only a mile or so from the motorway, so an easy and quick escape with stolen goods is available. Mind you, he also confirmed that there are many more desirable cars than mine parked on the street and driveways around us; he particularly fancies the Mercedes CLK just a few houses away.
I know that we really shouldn't expect much privacy these days, and that persons with nefarious intentions probably always cruised around the more affluent areas sizing up opportunities. But how much easier is it now to case the joint remotely with absolutely no chance of arousing suspicion? Want a new Range Rover in dark blue? A few hours on Street View will find you one, and maybe even give you some idea of how easy it will be to break in and steal the keys.
Mind you, I can't help wondering why there are so many cars parked on the street and on driveways. There's about a twenty houses around us and all have at least one garage, yet I know of only one person besides me who ever puts their car in it. Most people seem to think it's more important to store worthless junk there and leave a valuable car outside.
Of course, as any newsgroup or forum will tell you, worrying about stuff like this is just a sign you are paranoid. Street View doesn't show anything that isn't visible from the street, and the satellite images are supposedly too fuzzy to reveal anything useful. And you can always complain to Google and get your house or car removed or blurred; which, of course, just makes it even more interesting and attractive to virtual nefarious passers-by.
But thankfully our faceless bureaucratic rulers here in Europe are looking after our privacy. Starting this month they will be enforcing the new browser cookie rules that ban the use of tracking cookies without obtaining a user's prior consent. So at least when your car, garden tools, patio furniture, goldfish, and everything else valuable have been stolen you'll be happy in the knowledge that you can visit all your favorite websites without seeing targeted adverts.
Unless they also stole your laptop.
This week marked the start of a much hyped new BBC TV series called Planet Earth Live. Of course, being nature lovers, we had to tune in. Let's face it, who could fail to be tempted by a program that promises to reveal the intimate lives of wild animals, and is presented by two of our most lovable TV stars (neither of which, unfortunately, are wild animal experts - but that's just a minor detail).
And I have to say that the photography was just as amazing as we've got used to from similar BBC blockbusters such as Plant Earth (not Live), The Blue Planet, and the amazing Frozen Planet. Though showing some unrelated scraps of film of a lion's teeth just to illustrate how clever the camera operators are seemed a bit self-congratulatory. And the dreadful attempts at humour by the presenters, or that the one who specializes in shows about fast cars had to keep pointing out which of the big four wheel drive vehicles was his, surely didn't gain them any fans.
But where I began to wonder about the whole nature of this nature extravaganza, which will be broadcast twice a week for the rest of May, is that pretty much none of it is actually live. Other than the presenters doing the "walk and talk" stuff and some fairly vague "chat with map" bits that really told you nothing, everything was "action that we recorded earlier". Of course, it doesn't help that "live" here in the UK is the middle of the night where they are. Or that it was raining so heavily in the Masai Mara that nobody really wanted to go outside.
I suppose you can't expect a program to actually be "live" because it's likely that you'd sit there for the whole hour that it's on and nothing would happen. And it was cute to see the trailer for the bit where the meerkat is sitting on the cameraman's head. But, like so many of these programs, the focus is on "the human story" (even though they are animals) and focusing on the ones that aren't going to (or didn't) make it to adulthood.
While there are four huge prides of lions in the area, and it would be great to see how they live and behave, we instead had to watch a lone mother with a cub that is starving. Likewise, we had to see how a clueless mother in a leaderless group of elephants will (and did) lose her baby, and be told in detail how bad a mother one of the black bears is (until, thankfully, we discovered at the end of the sequence that she actually isn't that bad). But never mind, they did replay the cute "Ahhhhhh" moments several times, even accompanied by the presenter who'd just had a baby herself crying a bit to emphasize it.
But I suppose it's not as bad as The Big Cat Diary series where they were so short of material they had to show every clip six times, and then have three different people analyze each one. Or, as in the other nature program currently gracing our screens (Foxes Live: Wild in the City), keep telling us what other viewers are tweeting. If I wanted to know that, I'd look on Twitter. At least with Foxes Live you can go on the web and stare for hours at the live view from a camera, where nothing is happening.
It's a good thing David Attenborough is still alive or he'd be turning in his grave...
It seems to be a general rule now here at p&p that every guide we produce must have an associated set of practical examples so that users can get their hands (and keyboards) dirty playing with the technologies. It's almost like we're worried that our readers won’t believe the stuff actually works; or might think the text of the guide was dreamed up by the marketing department during one of their going forward, 360 degree, base-touching idea showers.
It's weird that I always dread the moment when the project manager suggests it's time to start on the Hands-On Labs (HOLs) for the guide we just shipped. The work involved in producing them always seems to vastly exceed any benefit users may get from them. Yet, once we get under way I really do enjoy working to the highly structured and predefined format. OK, so it takes an age to get the screenshots, the code, and the order of tasks correct; never mind the regular changes to the plan and the content. But it usually goes much better than I initially feared, stuff tends to work more easily than I expected, and it often comes together more quickly than I originally envisaged.
As you may have guessed from this pre-ramble, I'm doing HOLs at the moment; this time for the Windows Azure Hybrid Applications guide we recently released. And despite pages of instructions for setting up Service Bus, ACS, Traffic Manager, Azure Connect and more, the stuff is working as it should with only the minimum level of cursing and swearing at the technologies. We're well over half way through the ten labs, and still working to the original plan. Surely something must go wrong soon...
But where I am struggling is with the complexity of the technologies and the examples. Working with hybrid applications that use a wide range of networking services over the Internet means that the opportunities for simple one-line explanation of the operation are few and far between. Now combine that with features such as federated authentication, a fully architect-compliant application design that incorporates interminable levels of redirection, dependency injection, two MVC websites, WCF services, reliable messaging and connection retry mechanisms, and a multi-level Entity Framework based data model.
The result is that every step requires additional explanation of what the code does, and why. The rules for HOLs suggest each step should be a single instruction followed by a code listing or a screenshot, and that there should be minimum distraction from the steps themselves. Yet I'm finding I need to have up to three or four individual instructions in each step to be able to achieve something worthwhile in less than 20 steps, and each one seems to require a paragraph or more of explanation in a background box. And all this while complying with our new accessibility standard.
Users should be able to complete a HOL exercise within 30 to 40 minutes, and a complete lab in under an hour. Maybe that's possible if the exercise is how to create a class file in C# or write a WCF service that returns "Hello World", but it sure takes a lot longer to show users how to configure Service Bus and ACS when connecting a new partner organization to your existing hybrid application. Or to deploy the application to multiple datacenters, along with the data in SQL Azure and DataSync configured between all the instances.
What's mostly of concern, however, is the amount of time users of the labs will actually need to devote to understanding the theory and background to the exercises. Each lab has an overview with a schematic of the architecture for the example and the exercises, and then each task explains the objectives and the results. Meanwhile many steps have a couple of paragraphs explaining what's happening at each stage, and the code listings are interspersed with descriptions of how they work.
I guess I include all this extra content because I can’t see the point of someone going through the exercise just blindly following the instructions in the steps, without actually gaining any understanding of why they need to do it or any appreciation of how it all works.
But if our users end up spending more time reading than they do clicking and typing, have I actually created Hands-Off Labs?
Perhaps all countries, states, and regions are naturally capital-city-centric, but it's not often I am brutally reminded of that fact here in Ye Olde England where nowhere is very far away from anywhere else - at least in geographical terms. But, here in the wilds of rural Derbyshire, it's becoming increasingly clear just how far away we are in practical terms from the rest of the country.
Reading the newspaper, it seems like the world is about to end because of the most severe drought for fifty years. Reservoirs are empty, rivers have dried up, and it's so bad that our local water company is actually selling water to others elsewhere in the country. I read last week about how Severn Trent is pumping water into a local river that eventually feeds into the River Trent where Anglian Water is sucking it out again. I'm not sure how they know which water is theirs, or whether there'll be floods if they don't pump it out quickly enough.
Of course there's already a hosepipe ban on now in the majority of the country, with the most severe restrictions ever. They say that there'll soon be standpipes in the street and water rationing unless people start bathing in just half an inch of water. You'd think that we lived in the middle of a desert.
And every day there's a new crisis. Boat cruise companies will go out of business because the canals are closed. Public parks will become waste grounds as all the trees and bushes wither away. There'll be hundreds killed on the roads because cars will be so dirty you can’t see them. Garden centers will go bankrupt because nobody will buy plants. And then, when it does rain, there'll be flash floods because the ground is baked hard.
So while most of the country is reported to be drowning in both debt and drought, here in our glorious little haven of tranquility we're drowning in a lack of drought. Last December was the wettest for years, and it rained for most of March and all of April. At Easter it snowed. My lawn in like a quagmire, my fishpond is overflowing, and you need waders to walk through the woods next door. At one point recently it was raining at a rate of five inches per hour, and we even had hailstorms twice last week. Someone wrote to the letters page of my daily newspaper yesterday to ask if this was the wettest drought since records began.
Mind you, I did hear that our local recreation center is doing its bit to help. Due to the water shortage, they've closed two lanes of the swimming pool.
I bet you didn't know that the word "Wikipedia" actually means "fast child". And that the towns of Pendle Hill in Lancashire and Bredon Hill in Worcestershire both have names that mean "hill hill hill". No, neither did I until I bought Mark Forsyth's book "The Etymologicon" (which, incidentally, means "a manual for one who studies the history, and change in form or meaning, of words").
Mark writes a fascinating blog about etymology called The Inky Fool, and you can find links to the book on his blog. If, like me, you have a fascination with where words come from, how their meanings change over time, and how they relate to each other (and, in my case, how you can even make up your own new ones) then you really do need to buy a copy of this book.
The subtitle is "A Circular Stroll through the Hidden Connections of the English Language", and it certainly seems like it does both the hidden connections bit (which must have required an immense amount of research) and the circularity (especially as the final paragraph ends with "continued on page 1").
To give you a flavor of the style and content, I'm sure Mark won't mind me quoting some extracts from the very start, where he discusses what a book actually is. And, of course, due to the circular nature of the connections, the very end of the book does the same to complete the iteration:
"This is a book. The glorious insanities of the English language mean that you can do all sorts of odd and demeaning things to a book. You can cook it. You can bring a criminal to it, or, if the criminal refuses to be brought you can throw it at him."
From here, the topics move swiftly to "bookmakers" (who used to make books, but now take bets), to "a turn-up for the books" (which is really about bookmakers and not about books at all), to throwing stones at chickens in France.
Later, there's a section on frequentative suffixes that explains how people get to be gruntled (by grunting very often) before they can be disgruntled, one that discusses where the Cybermen came from (no, it wasn't Earth's twin planet Mondas), and one about how Bluetooth connectivity wouldn't have been called Bluetooth if the guy who invented it hadn't been reading about Vikings at the time.
And, most amazing of all, an explanation of why Winston Churchill's demands for wartime secrecy meant that tanks (the big iron things with tracks underneath and a gun on the front) didn't end up being called "carriers", or even "landships".
Meanwhile, the book will also tell you what the thing that used to be a "taximeter cabriolet" actually is today, and how the Von Trapp family were cruelly deceived because "do" is not a deer, a female deer, and "re" is not a drop of golden sun.
But if you want to know why Wikipedophiles are taking advantage of fast children, and why some people living in Lancashire and Yorkshire can't think of better names for their hills, you'll just have to buy a copy of the book...
Probably the most memorable comment from a snooker commentator was Ted Lowe during a Pot Black match in the late 1960s. Acknowledging the fact that in those days many viewers didn't have a color television, he helpfully noted "for those of you watching in black and white, the pink ball is next to the green". Question is: can I stay on the ball when I'm writing in black and white?
While Ted's comment might initially seem a bit daft, it was actually helpful. With the green ball on its spot at the baulk end of the table, any snooker fan would know which ball he meant. Unfortunately, the same can't be said of my current skirmishes with the new Microsoft Accessibility Standard (MAS) that's just come into operation. Yes, it's a good thing that we now have a fully documented and very necessary standard that details how to achieve optimum accessibility for all users of our content. But putting it into practice here at p&p is an interesting exercise.
The overall rule is simple enough: all documentation must be usable by every type of reader, using every type of input and output device, without mandating a specific type of hardware. In other words, we must not force a user to use a mouse or keyboard (they may be using a touch screen device or some other type of input device), or any type of screen or output device (they may be using a screen reader designed for those with low or no vision).
For many years before becoming a 'Softie, I specialized in conference presentations and articles related to maximizing web site accessibility. Web pages that work fine with no script support (such as in all types of screen readers), and which work without depending on color - a bit like Ted Lowe's snooker conundrum. In fact one of my slide decks had a title page consisting of six large buttons in various shades of gray, with an instruction below that said "Press the green button to start the presentation".
So I should be well versed in the technicalities of accessibility, but it's not so easy when you come to put it into practice with our relatively complex documents. In many cases, the stuff I create is architectural and developer guidance that talks concept and implementation, so it's just a case of text and schematics. OK, so the schematics aren't usable by those with low or no vision, but we do explain the contents in the surrounding text as best as we can. And we never depend on colors because our guidance is typically designed to be printed in monochrome as a book, as well as HTML on MSDN.
However, my current project is a series of Hands-On Labs related to the guide Building Hybrid Applications in the Cloud on Windows Azure. These are, of course, pages and pages of procedures with steps consisting of "click the Whatever button" and "press the Whoknowswhich key". Except now they aren't because we can't do this any more. It contravenes the MAS rules. I guess it always did, but we never really noticed because the labs are aimed at knowledgeable developers who we assume are familiar with Visual Studio and know the equivalent key presses, menus, and shortcuts.
I wondered if we would be exempt because we're just using Visual Studio, and the people who write the docs for it would have covered all the accessibility bases already. But that's not a reasonable approach - we need to make sure that we abide by the rules and offer the most accessible content to the widest range of users.
One solution suggested by MAS is to include all options for each user action, such as "Press Alt-Whatever followed by the Another key (or right-click and then click Whatever, or select Whatever from the Thatone menu)". But imagine how that will pan out when there are twenty steps in the procedure where each one requires three user actions, and Visual Studio has four different ways of carrying out each action.
Another alternative is to provide a table of equivalent actions. We'd need five columns, one each for mouse, keyboard, shortcut menu, shortcut key combination, and screen tap; and there'd be a row for every action for the whole lab. So the table could easily run to several pages, and is unlikely to be anywhere near useful.
We finally decided on the third option: be non-specific. Use words such as "select" and "choose" that don't imply any specific input device or method. For example, "Select Yes please and then choose OK". The selecting could be with a mouse scrolling a drop-down list, arrow keys, tapping with a finger, or through a voice-actuated screen reader device. The OK could be a mouse click, the Enter key, a screen tap, voice recognition, or the equivalent in any other configured input device.
However, there's another issue as well. We can't use relative visual position as a guide to a task because some devices may not display the screen contents in the same way, or may be audio screen readers. Therefore, instructions such as "In the left pane of the screen, click Whatever" or "Select the Another option below the textbox" won't comply with the rules. So some judicious re-wording is required to indicate which control we mean when there are several similar ones.
As I worked on the Hands-On Labs last week, I decided to make life easier for users by highlighting the required button, textbox, list, or option with a big red circle on the related screenshot for each step. That will make the newly added vagueness easier to cope with, though it's hard to see how it will help users with low or no vision. And I've yet to fully grasp the validity of using words such as "look" and "see" when guiding users through the steps and actions.
But it will certainly be interesting to discover how long it takes me to get used to not automatically typing "Click" at the start of each step...
Here in the UK, you have to wonder where our next generation of developers and programmers will come from. What has changed over the past twenty years that seems to be destroying the curiosity and passion we used to have for learning about computer language theory, algorithms, and programming techniques? Maybe it's a topic that is just too remote from modern life and young people's aspirations?
All this contemplation came about after reading about the new Raspberry Pi experimental computer. When I first heard about this I expected something like the old kits I used to play with back in the 80's; a row of lights that showed the binary result each time you entered a machine code operator using the row of switches and pressed the "Go" button. But things have come a long way since then. The Raspberry Pi has an O/S and UI, a development environment, and even powerful audio and video capabilities. It's pretty much a complete computer.
The idea is that kids will learn about computing using this, and older (post-school) users will take it up as a way to learn more about the internal working of computers and programming languages. It's an up-to-date version of the early home computers from Sinclair, Atari, Oric, Commodore, and others; a cheap and easy way to get into the real world of computing, rather than the esoteric and non-technical ICT (Information and Communication Technologies) stuff they teach in schools today.
I guess that, as a computer freak for more years that I care to recall, I find it hard to understand why kids don't seem to have the same passion for hardcore computing topics such as experimenting with different languages and learning about algorithms and programming techniques. Instead, they get taught how to use word processors and spreadsheets, and how to express themselves through email and social networking. Vital skills for the future, I agree, but hardly a way of raising their interest in the fascinating world of real computing.
I suppose that today's computers, tablets, phones, and other devices are more suited to producing results or integrating with lifestyles than being a useful platform for experimentation. Even writing programs has been reduced to simple drag/drop/configure tasks through the application frameworks and builders now in common use. Do you need to understand algorithmic programming and proof any longer? Do the tools remove the need for the basic skills and knowledge of programming logic and construction?
What is really startling, however, is the revelation in the article I was reading that out of 27,000 teachers who qualified in 2011 here in Britain, only three have degree in computer science. Less than 0.01 percent of new teachers have enough interest in "real" computing technologies and techniques to study it in depth. I guess there are thousands who can teach kids how to use Microsoft Word and send email, though I suspect that a lot of kids can already do that without needing lessons. And I suppose there are plenty of artistically-oriented teachers that can cover computer-based multimedia studies and creative activities. But who will kindle the desire to "know how it works" we had; something that surely must still reside in today's kids?
The aim of the Raspberry Pi project is "to bring real computing back to the classroom". The question is, who will define what "real computing" is today - and what will they decide?