Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • 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.

  • Writing ... or Just Practicing?

    Living in a Cage


    Funny stuff, wireless. We take for granted that we can wander aimlessly about the office or home while maintaining a robust connection to the outside world, or just to the server down the hall. Let's face it, modern kit and the connection it provides is pretty reliable. And, rather annoyingly, after the not inconsiderable effort of hard-wiring my house with CAT-5 and a 10MB switches, it even seems that the new generation of Wi-Fi is faster.

    And range is less and less a limiting factor. From my laptop sitting in the lounge, I can see five wireless networks that have almost as strong a signal as my own router than lives on top of the display cabinet in the dining room. OK, so I run it at half power, but I'm only five yards away from it while my nearest neighbor is thirty yards away. And I can even tell where some of them actually are because they insist on transmitting their own name as the SSID. I just hope they are properly secured.

    Anyway, where I'm going with this is that - in contrast to Wi-Fi - not much else wireless seems to work as reliably. I read endless articles about how vague and unreliable the latest 3G networks are when using a mobile phone or a dongle; and that many sat-navs seem to spend most of their life trying to find satellites. I bought a radio-controlled wristwatch a couple of years ago, and we have several radio-controlled clocks in our house. Yet, even though we're only 70 miles from one of the major time signal transmitters that's supposed to serve half of Western Europe, updates are sometimes sporadic. I think I've more chance of radio wave radiation burns from it than getting to know the correct time.

    But what really got me going was a recent purchase of a wireless weather station. I've been using some old-fashioned tools (such as a wood and brass barometer) and simple indoor weather monitors for a while. However, real outdoor weather measurement has so far tended to involve the more "manual" activity of looking out of the window, or actually going outside. So I expected the complexity of boxes and technology nailed to a post in the garden to be a real improvement over current methods.

    Yes there's gubbins to measure the wind, rain, temperature, pressure, humidity; and some other stuff that seems undecipherable (do I need to know what the "evapotranspiration" or "leaf wetness" is?). And it all shows up on a fancy wireless console you keep next to the TV, or on the coffee table as a talking point, as well as being uploadable to a PC. Unfortunately, the only way it would work is with the sensors sitting on the dining room table, or with the wireless console precariously propped in a bush in the garden.

    The wireless range is advertised as "up to 100 metres line of sight". Yet, even though it's only fifteen feet away and I can see it through the window, the feeble non-licensed signal can't manage to struggle over that distance to the receiving console. Even with new batteries, the maximum range turned out to be about three feet. Maybe I got a faulty one? I can understand that the signal can't be as powerful as Wi-Fi (it's supposed to run off two AA batteries for a year). But I might as well stand outside with a sprig of seaweed, hold a wet finger in the air, and take off my hat to see what the weather's like.

    Talking to the customer care department, it seems that this is a common problem. It's because I live in a Faraday Cage. Modern houses have metal foil on the back of the wall panels, and low-emissivity glass in the windows (which uses a very thin coating of metal oxide to reduce long wave radiated heat loss - I know this 'cos I used to be a double-glazing salesman). So getting a wireless signal in or out is obviously going to be very difficult. They did suggest keeping the batteries warm to maximize the signal strength. Have I bought a weather station that only works in summer? The "ice warning" obviously consists of a blank display.

    Strangely, they also suggest that "traditional brick and stone" walls, even very thick ones, cause a lot less signal attenuation. So the solution seems to be either hacking into one of my neighbor's Wi-Fi signals (which obviously isn't aware that it should be blocked by my walls and windows) to see if they know what the weather will be like. Or go and live in a castle.

  • Writing ... or Just Practicing?

    Honey, I Shrunk The Internet


    If any UK-based Internet users noticed that the Web was running a bit slow last Thursday, I apologize. Probably I was partly to blame. I managed to send an extremely large zip file on a four hundred mile round trip just to move it three quarters of an inch. I'm expecting a large invoice from my ISP to arrive any day now.

    How did I manage it I hear you ask? And, more likely, why? Well, in my continuing search to be eco-friendly I run a single server that hosts several Hyper-V virtual machines, one of which is my external Web server and another that is my main file store. As I export copies of the VMs regularly, I don't have any other specific mechanism for backing up individual files from the Web server. And, for security reasons, the Web server VM has only a single network connection going to the ADSL router and out onto the Web.

    So when I decided to back up just the Web sites, the only option other than reconfiguring the network was to zip them up, drop the zip file temporarily into the Web root folder, and then download it through a browser on the internal network. As the internal network also connects to the same ADSL router though the gateway and firewall server (another VM), the download runs at 100 MBits/sec and doesn't ever have to leave my server cabinet.

    Except I forgot about the ramifications of my recent venture into a more resilient connection with the outside world, which involves a cable Internet line and a load-balancing router on the gateway server. The cable line is ten times faster than the ADSL line, so (as you'd expect) the LB router decided to route my request for the zip file out through the cable connection.

    Therefore the zip file ended up travelling out from my ADSL router, over the wet string that is the phone line to my local exchange, via kilostream to the BT data centre in Birmingham, across some high speed optical fiber to TeleHouse in London, out west to the NTL data centre in Bristol, through several fiber cables and distribution routers back to the old Nynex Cable centre in Derby, out to the green box at the end of our street, via coax under my front lawn to the cable modem in my server cabinet, and back onto the other hard disk inside the same server as it came from.

    I have to admit that I noticed the download seemed to be taking a long time when I came back an hour later at it was still only at 85%. Next time, I promise I'll unplug the cable modem before I start... but isn't amazing what you can do with modern networking technology?

  • Writing ... or Just Practicing?

    A Picture's Worth a Thousand Wg8nX


    As a full-time 'Softie, I am - of course - a fully converted Binger. However, I occasionally pop across to the competition just to see what graphic they've used for the search engine name, designed to illustrate the particular day of the year. It's an interesting way to keep up with other cultures and see how clever the artists are that create meaningful designs using images that look like letters.

    This is, of course, a common way to produce an attractive logo whilst adding a bit of fun to it. But you do need to make sure that you maintain readability. For example, we use this logo for a local site related to feline identification and assistance in locating lost ones. Hopefully, the actual text that is the name of the site is obvious to all.

    So, on Christmas day, I popped across to Google to see what they'd done to celebrate the non-denominational gift-giving holiday period (as one of my very pc colleagues described it), and discovered that it said "Grmoi8". Or perhaps it was "GrhelB". Hard to be more precise because - other than the usual letter "G" - the remaining images bore almost no relationship to alphabetic characters.

    OK, so I know it's pretty easy to figure what the name of the site is when you get there. Even if you're struggling to decipher the URL in the address box, the fact that it says "Google Search" in big letters on one of the buttons tends to give the game away. Is it that "Google" has become such a well-known household expression (and verb) that they now only need to use the letter "G" to identify themselves?

    I tried navigating to http://www.g.com to see if they've decided to abandon the newly non-required letters altogether, but there's no sign of a search engine there. Probably because it resolves to the IP address - an Assigned Numbers Authority reserved address. So I guess there's no point in Microsoft trying to register b.com either.

    Of course, one of the annoying things about HTML is that you can't easily tell what fonts the user has installed - which is why CSS accepts standard font identifiers such as "serif" and "monospace" that the browser translates into the appropriate locally-installed font. It would be much easier if you could just specify a font such as those letters that look like cutouts from newspapers, or that have curly bits resembling some Olde English typeface that went wrong in the translation to digital form, and automatically send them down the pipe as GIFs if user didn't already have them. Without needing to install stuff or run some hosted process just to display them.

    What's more worrying, though, is that an increasing number of sites seem to use animations as the site name. I run IE8 in a quite viciously locked down mode for general browsing, and find that I now have to add lots of sites to the Trusted Sites Zone that I've never needed to before. Live Mail only works in that mode, never mind many other commercial shopping sites. And it's often impossible to read the pages and navigate many sites with scripting disabled because they rely on animations for content, and ASP.NET and JavaScript-powered postbacks for every link.

    In my days on the conference circuit I preached the accessibility recommendations (and legal requirements) on many occasions, but I rarely see any support for the more specialist user agents in these kinds of sites. Yet sites such as Amazon, MSDN, and many others seem to have figured how to do it in even the most locked down or non-standard browsers and user agents. I imagined some years ago that we'd nail the "only works with browser X" thing, but it seems even less the case as the years go by.

    For example, what's really annoying is that Visa Verify thing that pops up (or often doesn't in IE) just as you get to the end of a Web-based purchase. I've lost track of the number of times I've had to switch to Firefox and go through the whole shopping and checkout process again because the Visa site can't send me a working page. I guess that if our most trusted and respected institutions (?) can't make it work, what chance do the rest of us have?

  • Writing ... or Just Practicing?

    Derbyshire Does Global Warming



  • Writing ... or Just Practicing?

    Being Resolute...


    So we're out of the noughties and into the tens, and I suppose I should decide on some New Year (or, more likely, recycled from the last several years) resolutions. Of course, one of the nice things about being a married man is that you generally don't have to spend a lot of time trying to think of suitable topics to be resolute about. You can usually rely on "the better half" to provide some useful direction in these matters. Suggestions such as losing weight, getting more exercise, giving up smoking, going to bed earlier, and generally increasing the possibility I might live to see old age.

    But surely there are some more useful (and easier to keep) resolutions that I can come up with as we traverse into a new decade? Ones that there's at least a sporting chance I can keep until the middle of January? Having spent some inordinate amount of time pondering, I've come up with my own personal list. Feel free to borrow any that fit your lifestyle and situation.

    1. Accept that I'll never be able to look at a lambda expression and have even the broadest inkling of what it does without spending several hours taking it to pieces and reassembling it in a different order, often in a different language.
    2. Be nicer to the cats when they decide to sit right in the middle of my desk and pretend they are about to collapse from hunger just when - after several hours grappling with some complicated code - I'm about to figure out why it doesn't work.
    3. Learn the shortcut key sequences for Word 2007 so that it doesn't feel it has to continually remind me that I can "Keep typing the Office 2003 key sequence, or press ESCAPE to cancel".
    4. Upgrade my Windows 2008 servers to R2. Preferably without destroying my domain, or just giving up and buying new servers with it preinstalled.
    5. Accept that 86% is about as good as I'm ever going to get in FreeCell, and use the time I spend playing it to do something more useful. Such as getting better at Mahjong.
    6. Figure out how to switch PowerPoint templates in a way that means I don't have to go through all the slides individually reformatting them every time I change to a new template.
    7. Buy a replacement for the second monitor that displays everything in the top left corner of the screen in a bright yellow color.
    8. Understand Domain Driven Design without being hampered by the multitude of conflicting views and explanations.
    9. Discover some new words I can use in documentation to replace "leverage", "impact", and "functionality".
    10. Stop wasting inordinate amounts of time every year trying to think of New Year's Resolutions.


  • Writing ... or Just Practicing?

    Elf and Safety...


    One of the joys of living in England is the plentiful opportunities for amusement (and sometimes even amazement) due to the proliferation of daft laws and rules emanating from our near-expired Government. According to an article in last week's newspaper, it's now illegal to sell a grey squirrel. It's nice to know that the appropriate level of law and order is being enforced in these troubled times. But best of all are the ramifications of the "Elf and Safety" laws (as they are affectionally known) that now blight almost every aspect of our lives.

    I suppose it's kind of related to the area of computing I moan so vociferously about on regular occasions - protecting people from doing stupid things. I can understand that when I buy a potted plant at a garden centre, the stick that holds it upright has to have a big flat plastic cap on the top so I don't accidently poke my eye out, and I suppose it's logical that a packet of peanuts needs to carry a "May contain nuts" warning.

    So it follows that the computer software I use should also protect me from doing stupid things such as forgetting to save the document before closing Microsoft Word, or accidently formatting my system drive. Thankfully, with some very minor exceptions, we don't yet have multiple "Are you really, really sure you want to do this" dialogs. Though I wonder how long it will be before you need to tick a checkbox to agree to some legal contract each time you delete a file, in order to protect the software publisher from being sued for loss of data.

    And I see that MSDN is doing their bit to help me avoid installing the wrong version of software, or even following inappropriate advice in TechNet that might not be compatible with my O/S version. Whilst browsing for a fix for a problem on my Windows Server 2008 boxes the other day, I was presented with a big warning sign saying "This article applies to a different version of Windows than the one you are using. Content in this article may not be relevant to you. Please visit the Windows Vista Solution Center".

    Err... thanks. Yes, I do tend to avoid browsing any Web sites from the browser on the server. Especially as I'm usually logged on as an administrator (so I can actually do stuff), and the browser on the server has the Enhanced Security Configuration enabled so almost no Web site actually works anyway. Instead, I use my old non-domain desktop machine (which, perhaps surprisingly, is not running Windows Server 2008?) for general browsing. But I suppose you have to admit that maybe it does prevent some incorrect updates being applied.

    I guess the question is: how far should a company or organization have to go to protect people from themselves? Should it be illegal to sell scissors to anyone who doesn't have suitable training in their use and a certificate of proficiency (issued, no doubt, by the Department for Protection from Sharp Kitchen Implements)? Likewise, should computer users be forced to sign a statement absolving the manufacturer of liability before they can edit the Registry. Should there be a law against fiddling with virtual memory settings unless you are a certified engineer (suitably registered on some national database)? Anybody want to take a bet on how long it will be before these actually come to pass?

    If you think these are daft rules, how about the one that comes into force next year with regard to tobacco advertising. It will be illegal for cigarette packets and the associated display paraphernalia to carry any advertising at all. Somebody pointed out that the name of the brand is "advertising". I guess it will save the manufacturers money as all brands will be sold in plain white boxes. And, according to the new law, from under the counter. I'll probably have to sneak in to the shop in a large overcoat and dark glasses, and whisper conspiratorially to the shopkeeper. "Pssst... John... quick, gizza packet of the white things... here's a fiver... no questions asked...".

    But I suppose what kicked off all of this wild holiday rambling was the following picture I recently came across in the newspaper. Tragically, quite a few passengers were hurt in the accident.

    However, what caught my eye and got me wondering was the sign on the front of the bus. I can accept that, on "elf and safety" grounds, they'd need to display the warning that the bus was not in service so that people wouldn't hurt themselves trying to get on it when the door is ten feet off the ground and the seats are ninety degrees out of kilter with their normal position. But the bus was obviously "in service" when the accident happened (unless all the injured people were stowaways). So, who - and at what stage - did they change the sign on the front?

    Is there a standing instruction in the London bus driver's handbook that says that the first task in case of accident is to change the sign? Maybe there is a team of London Transport elf and safely inspectors who shadow each bus in case of an accident, and can be on the scene in minutes to change the sign. Or perhaps the Metropolitan Police have a directive that enforces this as the first task when arriving at an omnibus accident. Or could it be that - like modern mobile phones - the buses are equipped with a motion detector that automatically updates the display when it detects more than a pre-specified angle of rotation?

Page 30 of 40 (320 items) «2829303132»