Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    A Relentless Paper Chase (aka Painting Windows Azure)

    • 0 Comments

    Here in Britain we always used to refer to a job that was never-ending as "like painting the Forth Bridge." It came about because the people who paint the huge and magnificent railway bridge over the Firth of Forth in Scotland reportedly start at one end and it takes so long that, when they reach the other end, it's time to go back and start all over again.

    However, with the new type of paint they used this time it seems they won't need to do it again for 25 years (see this BBC story). So now we need to find another suitable phrase to describe endless tasks that are overtaken by circumstance. After a couple of years working on documentation and guidance for Windows Azure, I propose we replace it with "like documenting Windows Azure".

    See, here's the problem. When applications came in a pretty box with some floppy disks or a CD they tended to have a strict release schedule. You could write a book about Microsoft Access 1.0 (in fact, I did) without worrying that the product would be completely different before you could get your draft through edit and sent to the printer. Even when documenting features of the operating system, such as Active Server Pages, you could reckon to hit the streets well before they released a new version of Windows Server.

    But now that we are all web-enabled and Internet-driven, it seems like us poor documentation engineers have almost no chance of keeping up. Product teams can drop in new features any time they like, and entirely change the UI so that our step-by-step guides make no sense at all and all our screenshots are out of date by the time we get the pages onto MSDN. I mean, we're just putting the finishing touches to the third update of the p&p guide "Moving Applications to the Cloud" and so much has changed since we released the last update (July 2011) that we've ended up almost totally rewriting it.

    As well as adding in new content around Cloud Services, such as updated configuration techniques and our own Transient Fault Handling and Autoscaling Application Blocks, we widened the migration scenarios to include Windows Azure Virtual Machines, Web Sites, hosted SQL Server, and new connectivity options such as Virtual Networks. We also added in more guidance about choosing the appropriate migration path through the ever-increasing list of hosting options. And, of course, we had to rename everything that's now got a shiny new moniker (think "SQL Azure" and "Windows Live ID").

    We're really pleased with how the guide has evolved, and confidently expect the new content to be even more useful to architects and developers considering migration of on-premises applications to Windows Azure. But, at the point where we expect to release, there'll obviously be yet another update to the Windows Azure SDK that will impact the sample code. And then in the next portal refresh they'll probably add another bunch of new stuff so we're out of date again, before we can even get it to the printers.

    Meanwhile, the "Hybrid Applications" guide we released only six months ago, and the associated Hands-on Labs we released in May this year, is already starting to look a bit out of date because there's a brand new web portal; new services such as Virtual Machines, Web Sites, and Virtual Networks; and a whole new caching mechanism. This guide's on the list for an update, but we have the second guide in the series, "Developing Applications for the Cloud" to update before then.

    In fact I only just discovered that I'm now a member of the "sustained engineering team" here at p&p. At first I was a bit concerned it suggested that, up till now, we only engineered occasionally - when we weren't busy doing something else. Yet I've always considered myself to be a "documentation engineer" because creating guidance is a task I do all day every day; and it has just as strong a relationship with "real" engineering as writing code does.

    Documentation engineering is like building a luxury motor car. You sculpt an attractive and intuitive exterior and interior, design and build the underlying structure that connects all the parts together, manufacture (or source from third parties) the components that actually make it work in the most cost effective way, and assemble the whole thing into a package that people will want to use every day.

    The problem is that, unlike a car, you can't just paint your guidance a different color, put some fancy alloy wheels on it, and stick a new badge on the back every six months. You actually do have to re-engineer it each time. I did suggest to our project manager that he wander over to the Windows Azure development team's offices and hit them with a big stick until they promised to stop changing stuff. But he said that probably contravenes some company policy.

    Maybe, instead, we can get hold of some of that 25-year paint in time for the next update...

  • Writing ... or Just Practicing?

    The Wrong Type of Electricity

    • 0 Comments

    It's customary here in England to castigate British Rail for their outlandish non-service excuses. As far back as I can remember we've had "leaves on the line". Then, after they spent several million pounds on special cleaning trains, it morphed into "the wrong kind of leaves on the line". And of course, every winter when the entire British transport system grinds to a halt they blame "the wrong kind of snow." But this week I've been introduced to a new one: "the wrong kind of electricity".

    During the summer months I ply my lonely documentation engineering trade using a laptop and enjoying the almost-outdoorsness of the conservatory; soaking up the joys of summer, the birds singing in the trees, the fish splashing around in the pond, and a variety of country wildlife passing by. So when I noticed one of my regular computer suppliers was selling off Windows 7 laptops, no doubt to be ready for the imminent arrival of Windows 8, I thought it would be a good idea to pick up a decent 17" one to replace my aging 14" Dell Latitude. With age gradually degrading my eyesight I reckon I'll soon need all the screen space I can get.

    So when my nice new Inspiron arrived I powered it up, worked through the "configuring your computer" wizard, removed all the junk that they insist on installing, and started to list all the stuff I'll need to install. Until I noticed that the battery wasn't charging. So I fiddled with the power settings, dug around in the BIOS, tried a different power pack, and did all the usual pointless things like rebooting several times. No luck.

    So I dive into t'Internet to see if there's a known fix. Yes, according to several posts on the manufacturer's site and elsewhere there is. You replace the power supply board inside the computer at a cost of 35 pounds, or – if it's still under guarantee – send it back and they replace the motherboard. Mind you, there were several other suggestions, such as upgrading the BIOS and banging the power supply against a wall, but as I'd only had the machine for two hours none of these seemed to be an ideal solution. So I did the obvious – pack it up and send it back to the supplier as DoA (dead on arrival).

    Mind you, when I phoned the supplier and explained the problem the nice lady said that it would be OK if I kept it plugged into the mains socket because then it doesn't need the battery to be charged up. True, but as I pointed out to her, it's supposed to be a portable computer. I'll need a long piece of wire if I decide to use it the next time I'm travelling somewhere by train.

    And do I want a replacement? How common is the failure? To have it happen on a brand new machine is worrying. Yet, strangely, only a few weeks ago I noticed one time when I powered up my old Latitude that it displayed a message saying it didn't recognize my power pack, but then decided it did. Yet after wandering around the house I found five Dell laptop power packs and they all seem to be much the same. All 19.6 Volts, either 3.4 Amps or higher current rating. They all have the same two-pole plug, with the positive in the center. The only difference seems to be that the newer ones have 25 certificates of conformance on the label, while the older ones have around 15 (perhaps that's why they seem to get bigger each time - to make room for the larger label). 

    So how does the computer know which power pack I've plugged in? When I looked in the BIOS it said that the power pack was "65 Watts". Is there some high frequency modulation on the output that the computer can decipher? Or does it do the old electrician's trick of flicking the wires together to see if there's sparks, and measure the effect? Do all computers these days do the same thing? If I buy an unbranded replacement power pack will the computer pop up a window saying "You tight-fisted old miser - you don't really expect me to work with that do you?"

    And is all this extra complexity, which can obviously go wrong, really needed? How comfortable will I be with all my computers now if I feel I need to check that the power supply/computer interface is still working every time I switch one of them on? It seems like the usual suspicion most people have that the first thing to die on your computer will be the hard disk is no longer true. Now your computer may decide to stop working just because you're using the wrong kind of electricity...

     

  • Writing ... or Just Practicing?

    You Might Also Be Interested In...

    • 1 Comments

    According to Amazon, I'm interested in buying 5kg of peanuts, a multi-purpose screwdriver, some lithium batteries, Katie Price's latest autobiography, an album by Rhianna, and Mellissa and Doug's Chunky Animal Puzzle. Though, in addition to wondering why people now seem to need several autobiographies to describe one life, I'd have to say that I'm definitely not interested in any of these seemingly random recommendations.

    In the world of commerce, and in one of my previous lives in the retaining industry, they call it "related selling". If somebody buys a tin of paint, you make every effort to sell them a brush, wood filler, undercoat, sandpaper, masking tape, and brush cleaner. I've seen this technique double the value of a sale when done properly. It even works to the customers' advantage because they feel like they've been "looked after" and don't have to drive back to the store to get the things they forgot.

    However, in our superstore-based and technology-driven world it seems to be somewhat less precise and successful. Without the personal service of an assistant behind the counter, all superstores can do is organize displays so that related items are next to each other. But online there are much richer opportunities. Today Amazon's home page lists 35 items that I "might be interested in", and if I bother to click the links in each section it will show me another hundred or so.

    Of course, they create these lists by data-mining my previous purchase history. They know I bought a 5kg bag of peanuts only a week ago, so they must think I have some really voracious visitors to my bird feeder. And even though they only delivered the new batteries for my camera yesterday, they obviously think I'm a fanatical photographer and I'll need more already. And, yes, I did buy a new door lock about three months ago. Though, unless they have been secretly communicating with my wife, how do they know I haven't fitted it yet? Perhaps they think I don't have a screwdriver, and that's why it's in the "might be interested in" list.

    I suppose the book and album are there because they know my wife likes Katie Price and Rhianna, based on my history of buying birthday presents. Though neither she nor I have much interest in games designed for children aged 2 to 5. But best of all, after a minor confrontation over household dustbins on our last collection day, I bought a large self-adhesive number 2 to prevent future ownership confusion. Amazon is pleased to suggest that now I "might be interested in" a number 1 and a number 3 to go with it. Related sales algorithm failure, I suspect.

    And this lack of sensible related product selection isn't limited to online retailers. While I'm not a regular visitor to fast food outlets, we do occasionally partake of a drive-through. Now, I know that we're all supposed to be reducing our salt intake, but fries without salt seem very bland. Yet none of them include one of those tiny packets of salt by default - you have to ask for it. And then every time, without fail and despite asking for "one packet of salt" to go with the tiny bag of fries, they shove half a dozen packets into the bag. Perhaps somebody should tell their accountants.

    Mind you, they also include a dozen paper napkins - though I suspect that's because they know I'll get ketchup all down the front of my shirt...

  • Writing ... or Just Practicing?

    Brian Saved Four Hundred Pounds!

    • 1 Comments

    There's an advertisement on the radio at the moment that explains how a guy named Brian saved four hundred pounds (in money, not weight) on his car insurance by using some price comparison website. Most people I know only pay around half that amount in premiums, so is this a realistic claim? Perhaps you have to pay the first ten thousand pounds of any claim, or are covered only when the car is parked in the garage.

    The rules for advertising here in the UK insist that adverts reflect the experience of the majority of people, and are realistic and true, so we can assume that Brian must be just some ordinary guy with an ordinary car. Or rather, that Brian is a very stupid ordinary guy who never bothered to get a quote from other companies in the past and was happy being fleeced. The alternative is that the company chose specific criteria and found somebody who, with some unspecified insurance company, would get a very cheap quote.

    The point is that the vast majority of people will not save anywhere near this amount of money when using the site to find an insurer with approximately the same terms and levels of cover. In my experience, saving even fifty pounds is very unusual, and I change insurers almost every year to get the best price. In other words, the headline comparison is, to be blunt, complete balderdash.

    It's amazing that, in many other areas of advertising, they wouldn't stand a chance of getting away with this. ISPs that offer broadband services have been hammered here in the UK for advertising unrealistic "up to" speeds, such as "up to 24 MB", that most people will not achieve. Mind you, furniture stores can still get away with advertising a sofa as being 50% off when a cursory examination of the quality will reveal that there's no way it was ever worth the original price, and probably isn't even worth the discounted price.

    So maybe I can adopt the new relaxed truth approach to my computing guidance in future. Tell software designers that they can get their code to run ten times faster by using the MVC pattern in their web applications, or that dependency injection will increase the speed of their UI by 200%. If anyone complains I can tell them that I did the comparisons on "standard hardware". Firstly on a laptop with one MB of memory, and then compared the result to the same code running on a web farm of two hundred servers.

    But I suppose the core issue is: does anyone actually believe anything they read, hear, or see in adverts these days? Perhaps that's why adverts are becoming more surreal, and even meaningless. For example, I couldn't help noticing an advert from a company that makes plastic water filter jugs. They're trying to persuade people to throw away their boring clear plastic one and replace it with one in an exciting new color (red, green, or blue). The tag line in the advert explains that, because our bodies are made more of water than anything else, then the more enjoyable the water we drink, the better. I'm struggling to understand how the color of a plastic jug has an impact on the mental state of the drinker, but no doubt they've done a study based on the same kind of strict criteria as I did with MVC and dependency injection.

    Though I do remember seeing a cartoon some while back that showed a hardware store with a big sign saying "50% Off Ladders", with the small print "12ft now only 6ft, 10ft now only 5ft, 8ft now only 4ft"...

Page 1 of 1 (4 items)