Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    Weather It's Musical?


    If I told you that my wonderful wife bought me a Vantage Pro 2 for my birthday, you might be thinking I was now spending every afternoon outside polishing a gleaming new custom sports car, or happily installing loads of exciting new applications on a super-fast new computer. Or perhaps even spending my weekends taking flying lessons so we could pop over to the Continent for day trips. Well, not quite. The aforementioned piece of equipment rather worryingly resembles a large black bucket with a propeller sticking out of the top and a small white concertina hanging off the bottom.

    But it is nearly as exciting (well, it is if you are a weather geek). After a couple of failed attempts with cheap personal weather stations (see Living in a Cage), we decided to get something a little more robust and reliable. And, despite me grumbling about US-made technologies that make more noise than a snoring hippo (as in Cum On Feel The Noize), it's actually made in California. Shame I can't provide the same kinds of long hot sunny days it's probably expecting. Still, it is a neat piece of kit - solid and well put together, and (unlike most others) has a useful wireless range. It also has a solar panel to help keep the battery charged - which seems like an obvious idea when you think about it. The remote console is really nice. And, best of all, it comes with a data logger and USB output to a PC. Perfect for us IT-oriented folk.

    Except, as with so many other hardware companies that unwittingly wander into providing software, the PC application is less than optimal in design, functionality, and - more than anything else - appearance. I've moaned about this with other hardware stuff (including Ready for Hibernation). Probably they just put it out to tender and take the lowest quote. Though when you look at some of the home-made weather sites on the Internet, you soon come to the conclusion that weather-watching and an innate sense of design seem to be mutually exclusive tendencies. To protect the guilty, I won't pick out any specific ones... its common knowledge that developers have no sense of style.

    As a result of some Web searching, however, it seems that all of the serious weatherists out there use a piece of "donateware" called Cumulus. So I tried it and, wow, it is terrific! So good that I donated a reasonably generous sum on the grounds that software this good deserves support. It natively integrates with the Vantage station, and has a really neat and attractive UI that shows everything (and more) you could want to see. There's tons of graphs and charts available, it maintains history data and the high/low records, and it's really easy to configure.

    And, best of all, it has built-in Internet support. It dynamically generates a complete Web site based on templates that you can modify; it can post data to well-known world-wide weather aggregation sites; and has support for (almost) real time data refresh. Though I can't help wondering what effect writing the data file to the disk every five seconds will have in terms of MTBF. Hopefully, running a scheduled defrag task weekly will move it around the disk and save it wearing a hole on one place! But I guess the server O/S hits the disk just as hard during its day to day operation.

    Cumulus even have available for download a really nice bolt-on Silverlight interface that you can use with the real-time weather data file, as well as including a Flash widget that works in the standard Web site pages. You can easily expose a useful and attractive weather Web site from your own server or from a Web hosting company (providing you can upload the page updates through FTP). And you can specify the update intervals for all of the operations. So if for some inexplicable reason, while reading one of my weekly half-baked ruminations, you wonder what the weather is like here in this tiny remote outpost of the vast Microsoft empire you can go and see for yourself. Or even marvel at the real time version. And, just to prove that integration with other weather aggregation sites works, check out the PWS Project and, of course, Weather Underground.

    However, to see what you can really do with all the data you collect, you just have to go and listen to the music generated by the Weathersongs Project. They take the data from a weather station and process it into sounds. Listen to the "Autumn rainfall" one as a great example. Mind you, as their weather station is in Wales (the home of the world's greatest male voice choirs), you'd expect it to generate quality music. I doubt if the tuneless weather we get here in cold and windswept Derbyshire could compete.

  • Writing ... or Just Practicing?

    What's In Your Sandwich?


    One of the most amazing things about being in the US is the unending choice of stuff - everywhere. And that fact that everything seems to consist of all kinds of other things. Waiters in restaurants (except for the very high class ones) look at you gone out if you try to order a steak without three different kinds of stuffing inside and two sauces on top, not to mention the choice of five dressings for the side salad you don't want, and a selection from the option of six different kinds of potatoes.

    I can't imagine what Americans must think when they come to England. If you go into our local restaurant at lunchtime on a Sunday, they don't even ask you what you want - they just bring you beef and whatever vegetables and other accompaniments they decided to cook that week. Or, if you profess vegetarian tendencies, a nut and mushroom quiche. And, of course, chips (the proper English kind - not anything French, or flat disks of fried potato flour).

    OK, so maybe I'm exaggerating just a smidgeon here. And I've raved in the past about how hard it is to order something simple such as a coffee or a sandwich (see How p&p Makes Cheese Sandwiches). But, since then, I've been able to experience first-hand the competitive nature of sandwich ordering that prevails in many US locations - including the "fancy new building 37 cafeteria" mentioned in that post.

    After choosing the type of bread you want (I don't know the proper names, so I just have to ask for "that flat one"), you select from a range of over 30 different fillings. The lady behind the counter just keeps piling them on, without ever seeming to question the culinary combination and it's possible after-effects, or applying any limit to the number of selections you make. I tend to stop when the sandwich reaches a thickness that, after suitable squidging in the grill and afterwards by hand, roughly equates to the cross-sectional area of my mouth. But plenty of people appear to disregard this rule of thumb, and I'm convinced engage in a competition to see how tall they can make their sandwich before it won't actually fit in the Panini grill.

    Mind you, during my most recent on-site visit, I was relieved of the taxing sandwich assembly choice process one day when they ordered in a load of pre-packed sandwiches so we could continue a meeting over lunch. As expected, most of them were combinations of esoteric (and often, as far as I could tell, extraordinarily mismatched) fillings. I managed to find one with a mixture that seemed logical and reasonably harmless, grilled chicken and mozzarella. However, on reading the packet, I was stunned to discover that even this relatively unexciting delicacy contained some thirty plus different ingredients (as you can see here).

    Of course, that just started another competition - whose sandwich had the largest number of ingredients? After some frantic discussions and investigation, we found one that had 47 different ingredients. A clear winner (and, unfortunately, I can't remember now what it was advertised as). And, of course, all this activity totally disrupted the meeting, and pretty much negated the whole advantage of ordering in.

    Next time, I reckon I'll just order a cheeseburger. I'm sure there's only a couple of simple and wholesome ingredients in them...

  • Writing ... or Just Practicing?

    Location Dependent Narrative


    Perhaps it's just anecdotal evidence, but it seems like you often hear about people who are afraid of the countryside. For those of us brought up amongst fields, trees, and wildlife, this seems an extraordinary concept; though I guess - as I have a deep-rooted fear of cities - the converse is not as unlikely as you might imagine. Personally, I hate the bustle, noise, and smell of city centres such as London and Birmingham, and I can't imagine living in the midst of a constant rush of people, cars, and trucks; and the torrid sense of panic that life in general seems to require in these kinds of places.

    So it was refreshing to be reminded by a TV documentary the other week about the life of Roger Deakin, who wrote about the wildness and beauty of the English countryside in Suffolk and Essex. He died in 2006, but others (including Robert Macfarlane in the recent documentary) have continued his work, showing how even the most industrially despoiled landscapes and man-made ugliness slowly convert back to nature. One thing I found interesting was how Roger worked from many different locations when writing. He collected a range of wheeled "sheds", such as old railway wagons and carts, and parked them in different areas of his farm so that he could live and write in each one, depending on the season and the surroundings as they changed throughout the year. He said the style of his writing varied to reflect the features of each location, allowing him to change his view of topics and document them in different ways.

    It struck me how I, like many writers, tend to do much the same. OK, so I haven't adopted the local café as a base for writing adventures about a boy wizard, and I can't afford to go off and live in Madeira or the South of France for a year, but it does seem as though - despite establishing a fully-fitted modern office with all the things you might need to be an author - I still exhibit itinerant tendencies, depending on the type and content of the material I am charged to create. Certainly at this time of year, with snow lying and a distinct chill in the air, the centrally heated office is my usual home. However, in warmer seasons, I tend to migrate into the conservatory - usefully equipped with a desk, power, and a network socket; and a glorious view of the garden, the fishpond, the birdfeeders, and a small copse of trees. And, at various times, I find myself in the lounge writing with a laptop on my - err - lap, or sitting at the dining table, or even standing next to the server cabinet during those "not really at work but working" moments.

    And it seems that I do create different types of verbiage depending on the location. For many tasks, such as editing post review documents, creating schematics, teleconferencing, and writing and debugging code, I take advantage of the power of the big box and the screen space of two decent sized monitors in the upstairs office. And the view across the fields from this elevated location does make it a pleasant place to work at any time of year. In fact, most evenings find me wired to this machine through headphones for the conference calls and meetings that take place in US Pacific Coast Time mornings.

    But somehow, as the winter wears on, I can't wait to escape from the confines of the office, the random music stream from my media server, and the anti-SAD daylight lamp, into the warmth and brightness of the conservatory. It's probably as near as you can get to working outdoors without actually being outside. There's something special about the sun streaming in, the noise of water and fish splashing in the pond, the birdsong, and the occasional visit from a squirrel (or even, in the late afternoon, a vixen out early searching for food for her hungry cubs). And it's here that I find I can so much more easily write those more lyrical sections of content, such as technology overviews, chapter intros, articles, and my seemingly endless stream of rambling blog posts.

    Then there's the times I need short, sharp, to the point content. A good location for this is ensconced on the sofa in the lounge, or perched on the edge of a chair at the dining table, as my wife watches East Enders or Casualty on TV. The almost constant yelling and screaming (from the TV, not my wife) seems to suit this kind of writing - keeping it tense and to the point. Though it does tend to need additional editing after I calm down again.

    And then there's those "in-between" times when I just need to check my email or send a quick note. The server cabinet includes a machine that runs a locked-down Windows 7 installation where I can administer the virtual servers and network devices, and do general administrative fiddling when required. It's a perfect location for doing email and making brief notes because (a) I'm standing up, (b) it's cold in winter, and (c) I have to use Notepad to write stuff. It keeps me focused on the job in hand, and tends to concentrate the mind into producing concise output.

    The one place I find I cannot write, in a way that produces anything near to useful, is when I'm on site in the team room with all of my colleagues - as experienced in my recent trip across to Redmond. OK, so a constant stream of meetings doesn't help, but even when there are a couple of hours to sit down and get stuck in I find I'm struggling to concentrate. It seems like my head is full of extraneous distractions and the words just won't come. If this is an agile, writer in the room, close to the dev team process, I certainly need some serious practice to cope with it.

    Maybe, unconsciously, I relate it to my fear of cities - and the accompanying torrid sense of panic. The only saving grace is that the corresponding requirement to complete the necessary work in my hotel room in the evenings means that I don't actually have to watch US television programs. Not that they allow you to concentrate anyway. I tried to watch a late night political commentary show, which seems to allocate a maximum of four minutes to the program before breaking for five minutes of adverts. One of the guests was ex HP chief Carly Fiorina, who was fascinating to listen to. Here's someone with real world business experience who has something to say about the state of politics and government. Yet, after four minutes, the presenter stopped "for a word from our sponsors" and then - after the ads - started interviewing somebody entirely different! No wonder our kids suffer from Attention Deficit Hyperactivity Disorder.

    Mind you, back home again, there's something tempting about buying some disused railway wagon and getting it dumped in the wood to provide another alternative writing location. Maybe I could equip it with a small stove and a camp bed, like Roger did with his, and move in for a week to write a chapter about some really complex technology that requires absolute concentration. Though, as my culinary capabilities barely stretch beyond Corn Flakes, I'd probably need my wife to establish a food delivery schedule to prevent me starving to death.

  • Writing ... or Just Practicing?

    Image-inary Complexity


    Like most computer geeks, my needs are simple and few - a quad core box with a big disk, a decent connection to the 'Net, plus occasional injections of coffee and cold pizza. My daily bread-winning tasks generally involve only three applications: Outlook, Word, and Internet Explorer. Perhaps, when I feel exceptionally expressive, Visio might have an airing; though it's generally limited to a few boxes and arrows in boring colors.

    However, even though I spend most of my time buried deep in some crosscutting technology or structural architecture implementation, now and then I have to come up for air and get involved with documenting stuff that users can actually see. Which means I need to be able to capture screenshots of UI applications, and then massage them into a state that makes them suitable for inclusion in our documentation. For more years than I care to recall, I've used Paint Shop Pro for this. I started with version 2, and gradually upgraded to version 4. With the various fixes and updates, installing it involves three steps: install version 4.0, install the upgrade pack to version 4.1, and then install the 4.1 to 4.2 upgrade pack. It's a pain, but fairly quick and only required when I buy a new machine.

    But now I'm on 64-bit Windows 7. It seemed like a good idea at the time, but increasingly I'm finding "issues" with programs that I know and love; amongst them, Paint Shop Pro. Trying to install it just gives an error message saying that it is "not compatible with this version of Windows". Maybe the code does something evil I never knew about, or Windows simply considers software that old as not worthy of a shiny new operating system. Or it could just be the way it had been compiled. A colleague mumbled something about byte alignment (and I even managed to refrain from making dentist jokes).

    Anyway, the result is that I needed to find some other tool that can do screen capture, cropping, resizing, basic editing, color reduction, and basic filtering (such as sharpen and de-speckle). So, in some unaccountable fit of wild optimism, I went online and purchased a copy of the latest version of Paint Shop Pro - now called "Corel Paint Shop Pro Photo". I've been using it for a few weeks, yet I still haven't figured out how 90% of it works. Even the simplest task seems to involve three extra mouse clicks and a search through the help file.

    I've purposely avoided trying to learn programs such as Corel Draw and Adobe PhotoShop in the past because they were way too complex for my simple requirements. But they've managed to stuff so many things into the new version of Paint Shop Pro that it bears almost no relation to my old version. I suppose over time I'll come to appreciate the powerful features and additional capabilities. Maybe I can get a job moonlighting as a photographer just to recover the cost. But what's really annoying is my own inconsistency. I've regularly grumbled about how software is becoming so simplified that even stupid people can use it; yet here I am moaning about an application that actually does give you complete control over every aspect of the process.

    And what makes it worse is that - after spending $100 - I discover that the version of Paint included in Windows 7 does pretty much everything I need.

  • Writing ... or Just Practicing?

    Sock It to Me


    I was rather concerned to discover this week how little I know about socks. I have a colleague who is a sock expert - even to the extent of knitting her own in a most startling range of textures, colors, and styles. But it's not a topic that I personally considered to be vital information for life. OK, so I've been wearing them for more than 50 years, but - other than when playing rugby or being a boy scout - I've stuck with just plain boring black ones on the grounds that the daily foot adornment process then consists of simply grabbing any two from the sock drawer and putting them on.

    So you can imagine the shock when I watched my wife pairing up a pile of freshly laundered socks to see her carefully examining each one for the almost indiscernible "Pringle" logo and then dividing them into two separate heaps. Fascinated by the process, I eventually had to ask what she was doing. "I'm separating them into left and right ones", she informed me - with one of those "isn't it obvious" looks. Oh dear - it seems that I've I've been wandering around the world blatantly displaying my hosiery ignorance to all. Image the embarrassment when I realized that everyone has been able to see that my sock logos were facing the wrong way.

    But I suppose it's only another indication of all the stuff I really ought to know about, but haven't managed to keep up with. I've been reading about some of the exciting new features being punted for future (post 4.0) versions of ASP.NET and the .NET Framework, and with horror realized that I know almost nothing about many of the exciting new ones that were introduced in version 3.5 - never mind version 4.0. In the years I spent as an itinerant author and conference speaker, I specialized in ASP.NET. But since becoming a full time p&p-er, and spending what seems like my whole life delving into the internal workings of Enterprise Library and Unity, I've trailed way behind. Yes, I know about AJAX and MVC, though most of my practical experience with them was creating custom implementations to achieve the same result before .NET 3.0 even appeared.

    This fear of being left behind is common in our industry, and often the "new and scary stuff" turns out to be reasonably easy to grasp when you actually come to play with it. Most is evolution rather than revolution, and existing knowledge generally smoothes the path for getting up to speed. As an example, I've been somewhat slow in learning about WCF, but a requirement to implement some services with custom instance contexts for a recent project meant that I had to catch up quickly. Expecting to spend a frustrating week on it, I was pleasantly surprised to discover that I had something working after only one day's concerted effort.

    Maybe it's just an irrational fear of being overwhelmed. If you read Scott Guthrie's blog, you probably saw this post that, amongst other topics, discusses the constant changes occurring in the technology industry. It's certainly worth reading - even if his group is one of those responsible for the irrational fears! Make sure you read points "d" and "e" in the first section. And I especially liked his comment that "you will rarely win a debate with someone by telling them that they are stupid".

    Even if you are a sock expert...

  • Writing ... or Just Practicing?

    In Search Of An Up-to-Date Definition


    Maybe we've just been lucky with car insurance. When somebody reversed into the side of my wife's parked car some weeks ago, our insurance company sorted it all out with one phone call, got the car fixed within a week, and even aggressively pursued the other insurance company to get the excess we paid refunded. Somewhat different to a friend's experience where their budget insurer led them a merry dance for several weeks, and left them severely out of pocket at the end. After paying the premiums for years, they suddenly discovered they were barely covered for anything.

    But I've just had a similar experience with virus and malware protection. I've suffered over the years with the well-known issues surrounding many of the mainstream AV packages, such as instability, incompatibilities, and hassle installing and removing them; though newer versions have resolved a lot of these problems. Mostly I've tended to use packages such as CA, Norton, Avast, and AVG. However, since becoming a 'Softie, I've been forcibly migrated to the arms of our own threat management suite, Forefront.

    We have our own custom installer for Forefront, which connects the client application to the backend big iron that hosts the management infrastructure; and on my corporate domain-connected machine it seems to work fine. But installing the stand-alone client on other machines has been an interesting revelation in how we depend on stuff that may not actually be doing anything. For example, I just clicked "Update definitions" in Forefront, and it says I have the latest definitions installed. Yet when I go to the Malware Protection Center it tells me that there have been five new versions since then, and my current version is at least two days out of date. There are over 90 new threats identified since the version I've got installed. But clicking "Update definitions" does nothing.

    Mind you, I suspect it's partly to do with the fact that it keeps trying to send packets out through some weird ports, and my network firewall just bats them back again. The log full of connection errors would tend to confirm this, and probably not being able to talk to its big iron is not helping the situation. Though it's not just Forefront that seems to have had issues - the Windows Defender installation on a couple of Vista machines suddenly decided some months back that it was fed up downloading updates, and just stopped doing so.

    So, on all of these machines, I've switched to the new Microsoft Security Essentials package, and so far it seems to do what it should - though I notice that scans and definition updates only seem to spring into life when the machine is reasonably idle. My wife has a habit of switching on, doing her email, then immediately powering off again, and I generally find I need to turn the thing on while she's out to get it up to date. Last week it suddenly started flashing red and complaining that the definitions were a week out of date. Yet it refused to do anything about it despite being left it in peace for an hour to do its internal housekeeping. It looks like it doesn't attempt to "catch up" if it missed a scheduled scan by running one as soon as possible afterwards (which you'd assume it would do). And when you start a manual scan, it doesn't automatically download the latest definition files first. So even if my wife had decided to click the "Scan now" button - and, let's face it, why would she - it would scan using definition files seven days out of date.

    But what really annoyed me was that my locked down Web browser machine, which runs 24 hours a day and is mostly idling, suddenly popped up a warning that Forefront had out of date definitions. On investigating the stored definition files, it seems like it hasn't actually updated since November! Yet the Windows event log is full of blue "information" entries describing how hard it's working to protect my machine. So then I looked at the virus definition updates in my local Windows Software Update Service (WSUS), which religiously downloads Forefront updates every night (all 80MB, and there's usually three of them).

    Amazingly, all of these are marked as "Not Applicable" for all of my machines. Obviously Forefront, unlike Windows Defender, doesn't look in WSUS - but goes direct to somewhere else. I wonder how much bandwidth I've wasted in the last year downloading these. That reassuring green tick in WSUS for the machines, which I assumed meant I was fully patched and up to date, means nothing in terms of malware and virus protection. It seems like every machine on the network needs to download its own copy of the definitions every time. But maybe that's better from a security perspective.

    So now I'm migrating all of the non-domain-joined machines to Security Essentials, and my daily task before using each machine is to click the "Update" and "Scan now" links. Maybe the dev team for Security Essentials will help out by adding an option that you can set so it will download definitions and scan immediately if it missed a scheduled one. And one more thing guys, how about allowing us to schedule a mixture of scans? A quick scan every day and a full scan every week, for example.

    Then, after all this fun, I decided the next morning to have a more thorough look at the "dangerous" software installed on my wife's laptop and my Web browsing box. I have to say I wasn't prepared for the horrors I found. On the laptop Firefox was still version 3.0.6, Flash was a year out of date, Adobe Reader was two whole versions past its sell-by date, Shockwave at least two minor releases out of kilter (it was only recently installed), and Java a whole version number adrift. On my Web browser box Firefox was still an old version 3.5 release, and Adobe Reader required the latest updates (which I've actually been telling friends and neighbors to make sure they install on their home machines).

    The reason is, of course, that none of this stuff auto-updates when you are running as a non-admin user. OK, so you can't run Windows Update as a non-admin, but it does do it in the background automatically. Firefox grays out the "Check for updates" menu option, so you might think all is well and it's looking after you in the background. Nope - you need to log in as an administrator to be able to click the menu link, and to actually perform the update. The same seems to apply to Adobe Reader, though it removes the "Check for updates" link rather than disabling it. And what about Flash, Shockwave, Java, and all the other weird extensions that seem to be indispensible for Web browsing these days? How do I check if they're up to date? In the end, I just logged in as an admin, went to the respective sites, and installed the latest versions over the top of what was already there. Though there's probably some I missed because I've never heard of them before...

    I guess it's interesting to ponder over whether software should update itself automatically. Obviously the O/S needs to in order to protect the less technical users (the computing majority). But should other programs do this? For example, I wouldn't expect my text editor (TextPad) or picture editor (PaintShop Pro) to do this. I run versions that are well out of date on some machines because they do what I need and I can't justify buying and learning a new version. But stuff that exposes me to risk, such as Web browsers, email clients, and the associated browsing junk, surely should auto-update - at least to resolve security vulnerabilities.

    OK, so maybe there's a problem with them not being able to access the system if the updates aren't delivered through Microsoft Update. I did read a couple of blog posts that suggested the answer is to give all user accounts write and modify permission for your Program Files folder tree, but I'm not convinced that's a great plan. Though whether it introduces more risk than running out of date browser and Web software that has known vulnerabilities is an interesting question.

    Maybe I'm just naive, but why doesn't software that may expose you to risk simply pop up a warning when it's out of date but can't automatically update? I suppose there's the risk that users could be fooled into trying to install some malware that pretends to be an "essential update for your system". The problem is that the current situation seems to be full of holes, and maybe it's no wonder that viruses and malware continue to flourish and spread. Still, hopefully after this round of updates I'm covered for the time being.

    Or until somebody reverses into the side of my server cabinet...

  • Writing ... or Just Practicing?

    Cum On Feel The Noize


    Why is it that the U.S. manufacturing industry seems unable to make anything with an electric motor in it that works without generating enough noise to wake the dead (or, at least, the sleeping)? Its 2:00 AM in the morning, so the bathroom light has been turned off for more than three hours. And I'm not much in the mood for a Margarita, so I can quite happily manage without a constant supply of ice cubes. Though, as it's about 40 degrees (F) outside, I would like to have some heating please...

    Yes, as you may have guessed, I've done the 22 hours end-to-end trip to the Mother Ship again, and am comfortably ensconced in a not exactly salubrious hotel room just outside Redmond for a couple of weeks as we get ready to toss the first Beta version of Enterprise Library 5.0 out into the arms of the baying public. And it's certainly fortuitous that I remembered to bring my airplane passenger earplugs within me.

    In my little rented room, there's an air conditioner/heater, a large fridge/freezer, and a bathroom extractor fan. It seems like it's totally impossible to stop the bathroom extractor fan running - even if you turn out all the lights and sit in the dark for an hour. And the ice-maker in the freezer is designed to make clattering noises even when it's turned off and not actually making any ice. The fridge, freezer, and room heater motors are also obviously interconnected. As one switches off another one starts so that, together with the ever-active extractor fan, they provide a fascinating and ever-changing combination of whirring, clattering, rumbling, humming, and rattling noises.

    OK, so I come from a somewhat backward area of the world (England) where we don't believe in air conditioning, and we have a gas boiler hidden away in the garage rather than electric fan heaters, but - as a civilization - we have advanced far enough to have a fridge, a freezer, and bathrooms with extractor fans. The fridge and freezer in our house are more than ten years old, yet still only emit a very faint hum. And the extractor fan turns off after five minutes. Even the central heating pump, located in cupboard next to the bedroom, generates an only just perceptible whirring noise.

    Yes I can unplug my hotel room fridge at night (a procedure I've carried out during my last several stays here), and shut the bathroom door. But, even though I come from what we in England call "Oop North", where we're supposedly hardy enough to withstand the cold, I'm not hugely keen on waking up in the morning with icicles on my eyebrows like you see on those polar exploration documentaries. In fact, in relation to the geography of the UK, I really live in the North Midlands - so I'm nowhere near as hardy as many of the other more remote inhabitants of our tiny island group.

    It's a well-known fact that Geordies go to local football matches in mid Winter (and in Russia when they're playing away) wearing just a Newcastle United tee-shirt. And the people of South Wales go shopping at Tesco in their pyjamas in the middle of the coldest Winter nights (see this BBC News story if you don't believe me). Meanwhile, Scotsmen quite happily run round on top of hills throwing cabers as part of the Highland games wearing (supposedly) just a kilt as a nether-regions windbreak.

    Mind you, I did bring my MP3 player and noise-reducing headphones with me, so maybe I should just go out and buy one of those "relaxation" CDs. The sounds of waves breaking on a distant beach, or birdsong, or whales serenading each other hundreds of miles apart, perhaps. I suppose I could even go the whole hog and buy a DVD of a roaring log fire to play on the TV in the room, just to complete the effect of a nice cozy retreat away from home. Though the crackling noise would probably keep me awake.

    Oh, and this week's title? Check out this page.

  • Writing ... or Just Practicing?

    Your Giraffe Is Upside Down...


    Reading a UK computer magazine last week, I came across the delightful phrase "like playing a recording of a swarm of hornets to a group of blindfolded mime artists". It conjures up a vivid mental picture of events such as might occur at a product development meeting where somebody suggests rewriting a whole legacy application in Objective Fortran and linking the components using DCOM. Or allowing the marketing department to choose the name for your wonderful new product.

    Generally, I have to avoid such colorful language in the documentation I create. Somehow, flowery terms such as that may be felt to be taking the reader's attention away from the main points of the technical description, or even tending to make the software seem less than seriously "enterprise-capable". Let's face it, when you're trying to explain something like interception for virtual methods, or attribute-based validation at interface level, tempting users' minds to go wandering off and luxuriate in some wildly unrelated (or even humorous) description of the effects is unlikely to comply with the stringent rules of our style guide.

    However, at the moment I'm writing guides that are not technically "documentation". They're designed to be entertaining and make it fun to learn about the products. I probably can't get away with a "Mr. Bunny's Guide" equivalent - which, for example, shows a Visual Basic Form in both front view (useful) and top view (just a straight line). Besides which, I'm no good at drawing pictures of farmers and animals. But, maybe I can sneak some vivid descriptions past the editors.

    Perhaps I can describe the process of architecting an application as "like doing a crossword puzzle in a foreign language when they forgot to print the black squares and your pen's run out"? Or the complexity of writing a multi-threaded interception authorization behavior as "like explaining AC theory to someone who thinks the electricity leaks out of a light socket if you don't put a bulb in it"? And how about painting a picture of reaching feature complete and code freeze for your product as "like trying to finish a bowl of soup when sitting outside a French café in the pouring rain"?

    Unfortunately, one of my U.S. colleagues once described me as having a "British sense of humor" (notice that he missed the "u" out). I guess this is where it will all fall over because it's likely that a large proportion of the readers will have no idea at all what I'm talking about. Especially when it's been translated into a range of other languages. And I suppose it could get quite annoying if you have to re-read the same section a few times just to grasp what’s going on. Oh well, it was a thought.

    Mind you, talking of animals, several years ago a co-author and I decided to have a competition to see who could get the most lifelike picture of an animal created as one of those "boxes and arrows" schematics into a book. I managed to get an only-marginally-recognizable dog into one of mine, including the Internet "cloud" symbol for the result of processing various inputs - neatly positioned just below the tail. I assumed they'd cut or modify it during edit, but to my amazement it actually survived intact. I never did get round to mentioning it to the publisher. However, my co-author won the competition hands-down by including a very realistic giraffe, and disguising it by drawing it upside down. I complained about this, but he simply reminded me that the rules didn't specify orientation.

    And I guess that, if my editors read this, it's a lost cause now anyway. They (and our customers) will be seeing animals in all of my schematics. Maybe I've just invented a new form of the Rorschach Ink Blot test.

Page 30 of 41 (326 items) «2829303132»