Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    Another Bowl of Peeled Grapes Please, Waiter


    If all goes according to plan, I should be spread-eagled in a sun lounger on a foreign beach as you read this, with a copy of some second-rate espionage novel in one hand and a large and very cold beer in the other. Maybe even nodding to the passing waiter to bring another plate of canapés and a bowl of ready-peeled grapes, or passing the time of day with famous celebrities as they stroll slowly past splashing their feet in the warm clear blue water of the Mediterranean. I mean, we did book a really nice hotel; though - looking now at some photos posted on the Web by previous visitors of the construction site next door to it and the dilapidated street of half-demolished houses round the back - I'm not so sure.

    But, still, it will be a break from the hectic document engineering thing I do all the rest of the time. Having finally got round to taking a holiday this year, we decided on a week in Malta - somewhere we've been planning to go for some years. When I was young, we lived there for four years (my father was in the Royal Air Force) and it will be interesting to see how it's changed. Some friends who went there a few years ago set me a postcard of their hotel on the cliff at Golden Bay, pretty much where I remember there being a military firing range. We kids regularly used to dig up clips of shells on the beach below, to the horror of our parents. I wonder if the tin shack with its cool box full of ice-cream (the only facility on the beach at the time) is still there. I doubt it.

    To save the hassle of trying to coordinate flights and stuff, we just booked through a local travel agent. Let them earn their commission by doing all the hard work. But what's amazing is the volume of paperwork and the apparent complexity of organizing it all. When I book a trip to Redmond, I get a single PDF through email that contains all of the details of the flight, hotel, rental car, and other stuff. So far (and we hadn’t actually departed when I was writing this post) I've had over 40 pages of stuff from the travel agent for this trip. I've signed seven forms, and paid three different amounts on my credit card. There's so much bumph that they even send you a nice hard-backed folder to keep it all in. I wonder how much all that costs?

    And when I fly to Redmond, I just need to turn up at check-in and wave my passport. This trip, I've got at least three pieces of paper that list all the documents I need to have ready just to check in. They include a 24 page booklet that contains flight coupons, details of the hotel, accommodation terms, flight times and destination information, health warnings, travel advice, and - best of all - two vouchers for a free drink on the plane. I especially like that these have a picture of two intertwined champagne glasses on the front, and a stern warning on the back that they are "not valid for alcoholic drinks, including champagne".

    It also says I have to fill in a form with my name and home address, and the address of the place we'll be staying in Malta. Of course, they posted the form to me at my home address, and helpfully sent it along with a confirmation of the destination hotel address. You begin to wonder if it would have been less hassle just doing it all through Expedia from the start. Mind you, I was reading this week about a new ruling from the People's Republic of Europe that says if you are ill while on holiday, you can claim back your holiday and take it later. As you can generally rely on picking up some variation of airplane flu while travelling, maybe I'll be able to stay there until Christmas. They say the weather is nice there in the autumn.

  • Writing ... or Just Practicing?

    Generically Modified


    Despite being a writer by profession, and regularly castigating my colleagues for being recalcitrant in reviewing stuff I write, I actually dislike doing reviews myself. When I was an independent author (before I signed my life away to Microsoft), I was often approach by companies offering to pay me to write reviews of their products for their Web sites and literature. Even taking into account the presumed integrity of the author, this type of review seems somehow to be tainted when compared to an independent review by someone who doesn't stand to gain from it.

    Yet I depend on reviews and reviewers, of both the technical and editorial kind, not only as part of my daily job creating guidance, but also when buying stuff generally. If I'm looking to buy a new ADSL modem or NAS drive, I'm likely to check out the reviews from real users to see if the one I fancy (the product not the reviewer) is actually any good. A typical example is when recently researching mobile Internet connection dongles and packages (which, from the majority of reviews, all seem to be equally useless). If I'm looking to buy a book, I'll read the independent reviews from readers. Only when I'm buying something as personal as music do I tend to avoid being swayed by the opinions of others. But that's mainly because, underneath this suave and intellectual exterior (?), I'm really still a heavy metal fanatic with a weird taste in classic rock music.

    So I always feel that I should do my bit by contributing reviews where I think I can add some useful feedback to the discussion. And there's no point in writing a review unless you tell the truth. OK, so my blog is not generally known for being exceptionally high in factual content, but I do try very hard to be fair and even handed. So, let me start by saying that the latest book I've been reading is not actually bad - in fact, in general, it's well-written, informative, useful, and I didn't find any glaring errors in it.

    And as you are obviously now waiting for the "but", here is comes. I bought "Accelerated VB 2008" (APress, ISBN 1590598741) based on reviews and the publisher's blurb in order to provide the equivalent training for VB as I undertook with Jon Skeet's "C# In Depth" book (see Syntactic Strain). According to the aforementioned blurb, it covers precisely what you need to know to use VB 2008 (a.k.a. VB 9.0) and .NET 3.5 effectively. This includes the newer and more advanced features such as generics, operator overloading, anonymous methods, and exception management techniques. And a whole paragraph of the description talks about the coverage of LINQ, extension methods, lambda expressions, and other VB 9.0 features.

    Yes, the book covers these. But the really new and exciting stuff only gets a very brief summary in the introduction (5 pages), and just the final chapter of 43 pages. And the new topics I'm interested in get about a page each, yet there are 14 pages on using LINQ with XML. It's not that the VB 9.0 stuff isn't covered at all, but it certainly feels like it was added as an afterthought. OK, so there is a whole chapter earlier in the book devoted to generics, which is really quite good, and there is certainly adequate coverage of other VB 8.0 features. But it feels like the book is actually "Accelerated VB 2005 updated to VB 2008". And having been an independent author in a previous life I know that this is what happens. As soon as a new version of a product is announced, the publisher is hounding you to update your previous book to the new version. In three months. And without them paying you much money.

    I guess this is the core difference between the two books I've been using. "C# In Depth" feels like it's telling you a story, and the features of the versions of the languages are partially intertwined throughout so you understand how each addition to the languages serves a specific purpose and simplifies or extends previous features. "Accelerated VB 2008" feels more like a tutorial that aims to cover advanced uses of Visual Basic without really explaining the evolution and purpose of the language. For example, there's a whole 45 page chapter devoted to threading, which seems to me to be a feature of the .NET Framework rather than a feature of Visual Basic.

    Perhaps I expected something different because I was looking for a book that covered the new language features in depth, whereas "Accelerated VB 2008" feels more like it is aimed at bringing VB programmers who basically still write like they are using VBScript into the real world. But it surfaces issues that I suppose I always recognized are part of the overarching view of programmers and programming languages (at least in the Microsoft world). It's like VB programmers have to be protected from reality; and must always be reminded how you define a class, use an interface, and handle exceptions - irrespective of the "advancedness" of the book.

    Again, I must repeat that this is not a bad book. It is really quite good, and will be a useful addition to the Visual Basic programmer's library - especially if (like me) you are still a bit vague about generics, delegates, lambdas, and similar topics. It also helped me more clearly see how the process of creating and updating documentation is a lot harder than it may at first seem. When I work on updates to the guidance for new versions of our deliverables here at p&p (such as Enterprise Library) I try really hard to interweave the new features with the existing content. In the previous two versions, for example, we've completely reordered the sections and topics, added new overviews and "how to" sections, and modified the structure to give the new features the appropriate precedence alongside the existing ones. And it really can be tough to do when there's already over 1,000 pages of it.

    And while Jon's "C# in Depth" book did wind me up with its repeated use of the term "syntactic sugar", "Accelerated VB 2008" also has one overarching feature that I found extremely annoying. Like so many other books, they insist on printing complete listings of the example code, even when it covers two or more pages, with the explanation only at the end of the listing. The result is much page flipping to understand what's going on. But worst of all, when there is a minor change to one line of code to illustrate a feature of the language, they print the entire code again with no highlighted line or indication of where the change is until you read the text after the listing. After a while I started just believing what the text said because it seemed too much effort to go back and try and find the changed line.

    So here's a challenge. Is there a book out there that covers the language features of Visual Basic 8.0 and 9.0 without describing how to declare variables, write a class, handle exceptions, and interact with the basic .NET Framework classes? One that explains in detail how features such as extensions, lambdas, LINQ, and generics work, and which makes it easy to understand their purpose and usage? Or am I just expecting publishers to commission books that focus only on stuff that I've been to idle to learn about so far? Maybe a market sector consisting of one person is not a viable business proposition...

  • Writing ... or Just Practicing?

    Dislocation, Dislocation, Dislocation


    With appropriate acknowledgment to Phil and Kirstie, this week's random blather seems to have evolved with a dislocated theme; and rather more so than is usual in my weekly ramblings. It started with a series of events that made me wonder if I am somehow dislocated from the rest of my corporate employees and the huge organization of which I'm part. Mainly due to some unexpected emails that popped up in my Inbox.

    The first was from a company that specializes in providing support for remote workers. I'm not sure if they meant remote as in working in the Outer Hebrides, or just remote as being home-based rather than enjoying your own cubicle or corner of an open plan office. Mind you, at 5,176 miles away from my office (according to KLM airlines, and not taking into account driving to the airport or continental drift) I guess I fit quite neatly into the "remote worker" category. Of course, this was just untargeted junk mail, but the following day I started to get more concerned when I found I'd been joined to one of our new corporate internal mailing lists called the "Remote Employees Group".

    It didn't actually say whether the remoteness of employees was associated with a character trait or with physical location, but I'm assuming the latter until I see some emails on the list. Though, as they failed to include the posting email address of the list (the email they sent was a "no reply" one), it might be a while before there's anything useful on there. I have no idea how they actually found me either. I try and keep my head down most of the time, so maybe somebody sneaked on me. Worried I'm not getting enough support for my daily task of sitting in front of a computer writing stuff about enterprise application design. Perhaps they'll send me a life. Probably as a zip file.

    It seems I'm also dislocated from my new Internet provider, as you may have inferred from last week's diatribe. Not dislocated in terms of physical connection, but just in terms of them actually accepting that I exist. No amount of contact with their customer services department can seem to unravel the mystery of where my account (if I do have one) resides. Although the fact that they got my name, address, phone number, and email address wrong on the one piece of paper that the fitters left me might somehow be a related factor. Mind you, while the ones and zeros continue to flow, I suppose I shouldn't complain. But I do wonder who is paying the bills.

    And how about being dislocated from my hard disk? I reckon I've discovered how software companies force you to upgrade stuff. When I joined the brave new world of SATA drives and Vista a while ago, I discovered that my disk backup imaging software (Acronis True Image 6.0) couldn't read these drives, so I had to upgrade to version 10. But this doesn't recognize the hard disk in our new Media Center box, so I've had to upgrade again to the "2009" version. I wonder what is different about the SATA disk in this box that means I need the new version. Maybe it just looks at the earliest file dates on the disk and decides it's time I paid them some more money.

    Though at around $50 it is a cheap solution compared to upgrading to Vista Ultimate just to be able to do disk images, and - more than anything - I trust it to actually do what I want. I managed to restore the old Media Center O/S with it more than once from saved disk images, and used it when replacing the boot drive in another machine. And a neat trick in the new version is that you can tell it to omit specific file types from the image it generates. So I don't have to include all the saved TV programs that Media Center stores in the Public Users folder. Otherwise the image process would probably take a week.

    But, after all that, what really prompted this week's dislocated theme was hearing that a colleague was going into hospital to have his dislocated toe relocated. It sounded an odd term to use, and - as my understanding of the finer nuances of the American language is still somewhat less than comprehensive - I looked up "relocated" in the dictionary. It seems that it means "moved to a new location, such as a different office, building, or city". I suggested he have a word with the surgeons before they start to find out where it will be afterwards...

  • Writing ... or Just Practicing?

    Cable Internet in 10 Easy Steps


    After what seems like a nightmare week of aggravation, it looks like I'm finally connectivity-wealthy. Downloads take seconds, uploads are relatively quick, and I'm probably even redundant connection-enabled. Though tests of the load-balancing and failover router have exposed some uncertainty around it's operating capabilities. Maybe it's something to do with the fact I bought the $250 one instead of the $1900 one that my colleague (who works for Cisco) recommended. I think he's planning a world cruise, and had his eye on the commission.

    Mind you, the LinkSys RV042 is a neat piece of kit. The default setup was easy, though mainly because in my case it just connects to two separate modems (rather than having to handle PPoE or something equally esoteric). When configured to do load balancing, it pings a specified address to determine which connections are available, and shares the load between them - though it sometimes seems a little reluctant to pick up a lost connection when that service comes back up again. I suppose that repeatedly pulling the cables out of the back and plugging them in again confused the system after a while.

    TIP: Run a tracert to a Web site to see the IP address of your ISP's host server that you connect to (the first entry after your own router), and use this in the service detection settings. If you point to the default gateway, it may not detect a fault beyond your own modem or router. If you point to your favorite Web site and it goes down, the router will think that the connection has failed.

    The only other downside I found so far is that setting up protocol bindings seems to be a hit and miss affair. I wanted to direct all SMTP traffic from my internal server (such as status messages from WSUS, the UPSs, and other bits of kit) through one of the WAN connections and have everything else balanced across both WAN connections, but an hour spent playing with protocol binding rules proved totally futile. The help file is suitably vague about doing something as complicated (?) as this. It does say that you can have up to 100 protocol binding rules, so maybe I just gave up too soon. To be honest, I couldn't be bothered setting up one for every protocol for both connection ports to see if that worked...

    Of course, as you can imagine, most of the aggravation this week was not with the router, but with the cable company. So, based on my experiences as a Virgin in this area, and there being No Time Like the present (if you're in the UK, this is a hint as to the cable provider), here's my top ten easy steps to getting cable-enabled:

    1. When you originally talk to the sales people, and they happen to mention that your next door neighbor's address is "coming up on their system" but yours is not, immediately put the phone down and call another company.
    2. If you failed to follow the advice above (which is likely in England because there is only one cable company), stand outside your neighbor's house when the surveyor or installers are due. Despite telling them several times where you live, they won't believe you.
    3. If you really depend on your connection, or do anything other than plug a couple of computers into the back of the modem, brace yourself and order a business service. And make sure you understand which packages can be configured with a static IP address if you need one (though they are not actually public static addresses), and the variations in upload speed between packages. Strangely, there may be "business rules" that prevent you having a static IP address on the packages with higher upload speeds (a situation for which nobody can explain the logic).
    4. Be nice to the fitters. Make them cups of tea and talk about football and cars. It also helps if you prepare the ground up front, such as digging the trench and putting in conduit for the cable so that, when your wife decides to plant geraniums in the flower bed next to the cable box, she won't dig though your cable.
    5. Buy some hefty cable clips to cope with the several extra yards of half-inch thick coax they'll leave curled up inside your server cabinet "just in case you want to move the modem somewhere else" (like next door perhaps?)
    6. After the installers have gone home, if you are wondering why your modem is running hot enough to fry an egg, remove the sticker with all of the dire warnings about connecting and registering the modem. This reveals the air vent holes. In fact, underneath the warning label you'll probably find another smaller one that says "WARNING: Do not cover these vent holes".
    7. Phone you supplier immediately after the installation is finished to see if they know who you are. If you are lucky enough for them to accept your address and the order number on the installation paper as being valid, ask them for a pin code so you can talk directly to technical support. It won't actually help, but you do get to listen to some different "on hold" music.
    8. Alternatively, if you find that the company actually doesn't know - or believe - that you exist (recall that your address is "not coming up on their system"), make a decision about whether to just keep quiet and see if you've actually got free cable, or whether you have the energy and patience to persuade them that you're not just a fig leaf of their imagination.
    9. Test all of the applications and services you use. They'll suddenly remember to tell you (after the installation is complete) that, for example, you can't connect to a VPN if you have not ordered your service with a static IP address. Don't panic, however, because this isn't true - it often does work with a dynamic address. However, if you want to send email from your SMTP server, that won't work unless you find a way to route it through their email servers. But if you are only sending yourself status messages, you may be able to set up a filter at your email host that allows you to bypass the Dynamic User List (DUL) checks on received email.
    10. Run a speed test several times to get an idea of whether you got the package you ordered. A good site is http://www.speedtest.net/. You will probably find that the results vary, though they stabilize after a few runs and should come close to the advertized speeds unless you run them at the busiest time. If you are running them from a laptop connected over your own wireless connection or through a 10MB switch, don't expect to get results higher than they can manage (and, yes, I fell for this one)!

    So, after all that, was it worth the aggravation? The jury is still out on whether they will actually come round to accepting that I do exist, and I'm a little concerned about the technical capabilities of the support people in connection with business issues, but time will tell. But at least there are lots more pretty flickery lights in the server cabinet now. Maybe in December we can drag it into the lounge and save on buying a Christmas tree...

Page 1 of 1 (4 items)