Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

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


Page 1 of 1 (6 items)