Random Disconnected Diatribes of a p&p Documentation Engineer
First off, I need to apologize to all those people who have been reduced to reading my previous "Hyper-Ventilating" posts hoping to find some crumb of comfort to alleviate their crippling medical condition. It seems from the analysis of Web search requests for those posts that more people are ill than are using Hyper-V. I suppose that's reasonable, and will perhaps teach me to stop using misleading (and often incomprehensible) titles for my posts. A bit like this one, I guess.
Ah, but no, this week's title is actually highly accurate! Because, despite endlessly installing and re-installing the Hyper-V integration components in my Windows XP and Windows Server 2003 virtual machines, Hyper-V seems totally incapable of displaying the appropriate cursor or mouse pointer. It always starts off OK, leading me to believe that it was just some intermittent aberration last time, and from now on I'll be able to see the pointer wherever it gaily wanders across the multiple windows and icons of the vast 800 x 600 pixel screen estate it has to play in.
And then it changes to a thin black "up arrow", or an hourglass, or even the tiny little square that's supposed to indicate that Hyper-V is letting you see the virtual machine even though you haven't clicked on it yet. But I'll say one thing - it's certainly making me learn where the "hotspot" is on each of the multitude of pointer and cursor shapes. No doubt that will be useful in some future life after the Government of the People's Republic of Europe bans all pointer shapes except "East-West-Arrow" or "No Drop". Maybe Microsoft should be planning their court appeal now, along with the one where the EU decide that MS has to take keyboard support out of the operating system in order to "level the playing field for competitors" (OK, so I made that one up).
Anyway, I know I'm not alone on this one. There are literally several people complaining on the Web about the same problem. Of course, I was quietly confident that they would fix it in this month's Patch Tuesday selection, but it seems not. Although, so far, the pointer appears to be firmly jammed in "standard arrow pointer" mode now, which isn't so bad. I can probably risk changing the desktop background back from sky blue into something that doesn't require me to wear sunglasses, and still be able to find the pointer on the screen. Before you ask, yes I did try changing the mouse pointer scheme in the virtual machine to one that's easier to see, but it's obvious after doing that (with its total lack of effect) that it is the Hyper-V runtime that's actually generating and managing the mouse pointer. So perhaps I should be grateful I actually get a pointer at all. I suppose I could try changing the mouse scheme in the base O\S instead...
And, while I'm ranting about Hyper-V, can we have some absolute guidance on how to do time synchronization please? After the aforementioned medical condition, this seems to be the second most popular search that finds my posts. Despite the fix I put in place some weeks ago, I was still getting a raft of errors in the Event Logs. Some helpful feedback from Virtual PC Guy and his colleagues suggested that there is a delay in the time synchronization from the Hyper-V base O/S, and that can cause synchronization failures against external time providers or domain controllers.
The problem I found is that, even if I remove all time provider details from domain member virtual machines, they insist on searching for a time provider and inevitably end up snuggling up to the domain controller (as you'd expect). I did wonder about disabling the Windows Time service on virtual machines and just allowing the base O\S to set the time - I reckon I can live with being half a second adrift from the rest of the world. But I have no idea if that would break anything else, and nobody seems able to tell me. And other than disabling the service, I can't see how else you can prevent it from searching for time providers. The other alternative, and the one I've now settled with, is to set up the domain controller(s) as reliable time servers and turn off the Hyper-V "VM IC Time Synchronization Provider" to prevent time synchronization from the base O\S.
Start by opening the Hyper-V Manager and select the virtual machine - it doesn't matter if it's running or not. Open the Settings dialog and click on the Integration Services section near the bottom. Then simply uncheck the setting for Time Synchronization. Now go to Configure the Windows Time Service and follow the instructions. To find an NTP server to use, check out the NTP Pool Project. A bathing costume is not required.
Before we start, I want to make it clear that - although I often use US spelling in stuff I write - I refuse to accept that "tire" is a way of spelling the round black things that you put on a car. I'm English, and tired (sorry) of seeing that weird spelling, so from here on in we'll be using the proper spelling: "tyre". And, annoyingly, Word has just red-wigglyed that now I've typed it. I guess an indication of how I have to produce most of my verbiage with Word set to US English. And this post is not even about spelling or languages. What is it about? I suppose it's kind of another grumble about technology in general. And about measuring stuff. So, if you are already in a bad mood, this might be a good place to stop reading and go off and do some yoga or listen to a Coldplay album.
It all started when my wife came home with a gleaming new set of bathroom scales (though, as there was only one of them, maybe it should be "a bathroom scale"). Like most gadgets and appliances these days, it proudly proclaims that it has a "bright and easy-to-read" digital display. And, more than that, it can tell you all about your health - things like your body mass index, water retention rate, and overall wellbeing. And probably your shoe size as well. "Amazing!" I thought, "I wonder how it knows all that".
The answer is, of course, that when you first put the batteries in, it asks you loads of questions such as your height, age, body shape (you get five choices for this one), exercise regime (four choices), and sex (you only get two choices for this one). This would be OK, but we unfortunately fell at the first hurdle. Despite wiggling the switch underneath to tell it to display in stones and pounds, it insisted my wife enter her height in centimetres. We are both of that lost generation who learned imperial measures at school, and now find ourselves cast adrift into a whole new world of metric things. It's like going in to work one day to find the management has ruled that everyone and everything will now be spoken/read/written in a foreign language. One you don't understand.
I know that a foot is around 300 millimetres, or 30 centimetres, or 0.3 metres (see how complicated it is already), and a metre is a bit over a yard. So I can do mental calculations such as converting "it's about 300 metres on the left" into roughly 325 yards or nearly 1000 feet. Of course, everyone in England blames the French for us losing our proper system of measures (it must be their fault because the letters in "meter" are the wrong way round). Just because they think it's easier than remembering that there are 12 inches in a foot, 3 feet in a yard, 5.5 yards in a perch, 4 perches in a chain, 10 chains in a furlong, and 8 furlongs in a mile. I mean, what's complicated about that?
So I used a calculator on the Web to do the conversion, and we finally got to the bit where it said "setting saved". Except that, when you stand on it, all it does for 10 seconds is display a fascinating series of flashing light trails across the "bright and easy-to-read" digital display, followed by "Error". We're nearly an hour in and still no sign of being able to find out our weights. Not even in some funny unit like kilograms. I know how to convert those into proper weights because I remember the mnemonic "One and three-quarter pounds of jam weighs about a kilogram". Except that, as someone pointed out a few weeks ago, it's not a very good memory aid because the important bit ("one and three-quarter") doesn't actually rhyme with anything. So it could just as easily be "one and a quarter", or "two and a half", or "one hundred and seventy three".
Anyway, having dispatched my wife to the store where she bought the scale to exchange it for a new one, we started the process again. At the end, when it came to the "stand on it and see what you weigh" moment, we got a different result this time. It said "Err-374". Thing is, we weren't interested in it telling us our BMI, liquidity ratio, or some meaningless number that relates to our wellbeing. Certainly, by now, my wellbeing was not what it was two hours ago. Why can't it just tell you your weight? Maybe even, and here's a shocking thought, by using a big calibrated spring with a pointer on the end that goes round a dial covered in numbers. After all, inside there's probably just a big spring connected to sensor that sends signals to the chip that converts them into numbers (or not in our case). So it's not like it's any more accurate or reliable.
This worrying advance in digital displays is not confined to bathroom scales either. I splashed out a noticeable volume of cash some while ago on a digital tyre pressure gauge because all the old-fashioned ones I have give slightly different readings, and I thought it would be a good idea to get a proper accurate and reliable one to replace them. No chance. Not only does it decide at random what units to display the result in, but consecutive readings seem to vary by 20%. And none are near to the average of my old-fashioned manual ones. The one that seems to be most accurate is the "looks like a pen and the inside pops up" kind like my Dad used to use when I was a kid. In fact, it's probably the same one.
And here we come up against another unit protest. Tyre pressures have always been measured in pounds per square inch, which seems innately sensible because the common range goes from about 30 to near 60 so it's easy to read and adjust the pressure. Get within a couple of p.s.i and its fine. But my new car handbook has all the tyre pressures in BARs. Not even in a semi-believable foreign measure like millimetres per second or kilograms per hectare. Can you imagine the people who invented this in some design meeting?
Marketing guy: "We need a new way to measure the pressure in car tyres."Engineer: "OK, how about we use a scale that starts at one and nearly goes up to three?"Accountant: "Sounds great - that will save on printing costs and we'll need less numbers on the dial."Manager: "That's a wrap, do it!"
OK, so I know that BAR is connected with atmospheric pressure, but now instead of "36 p.s.i. all round" I have to figure out where 2.18 is on the tiny dial of one of my other old-fashioned gauges that only has a marking every half a BAR. I suppose it's something to do with the European Union - most everything else is their fault. Just think how easy it would be if our global society could actually get to grips with using some standard measures and units for things. Starting, please, with time zones. I'm time shifted by 8 hours from my work colleagues, though for a couple of weeks of the year it's actually 7 hours or 9 hours because we can't even agree when daylight saving time starts and ends. Wouldn't it be easy if we all just switched to a single World time, like the Swatch Internet time that's been around for ages.
Except that we'd need to make sure it didn't change our four o'clock teatime here in England, when we all stop for cucumber sandwiches and a pot of Earl Grey.
I read in the newspaper this week that scientists have discovered why men are better at reading maps, while women are more able to find things like car keys. It seems that it all goes back to pre-history behavioral patterns and responsibilities. Men had to travel long distances hunting, and so had to be able to navigate. Women foraged locally for food, so needed a keen eye for detail. Now I don't want to appear sexist, but I have to say that, at least in our house, reality tends the match that assertion. Mind you, one guy wrote in to the paper to say that his wife was really good at map reading - as long as they were heading north.
Even more interesting, I've come to the conclusion that, for some indeterminable reason probably long lost in the mists of time, women who like cats tend to marry men who work with computers. It's kind of hard to justify this on a "back at the dawn of time" basis, or in terms of a theory based on studies of Stone Age cave paintings. Mainly, I suspect, because there was a noticeable scarcity of computers in those days. And it's probably a long shot to try and find some comparison between map reading abilities and an innate ability to absorb computer language syntax and structured architectural design patterns. Other, of course, than using a sat-nav.
Not being one to jump to wild conclusions, I have obtained solid statistical evidence of the marital preference assertion. My wife is a cat-lover, and does a lot of work raising money for our local cat sanctuary. The lady who runs the sanctuary is married to a guy who writes medical software for hospitals. One of the ladies who help to run the money-raising jumble (rummage) sales is married to a guy who works for a well-known manufacturer of routers and switches. And her friend is married to a guy who runs a business doing computerized accounting systems.
And what's really weird about the cat rule is that, when I first met my wife, I didn’t actually work with computers. I was a salesman. OK, so I was selling windows at the time, but they were ones you put into buses, trains, and office blocks - not the one I spend my days fighting with now. So obviously the theory extends to future employment prospects as well.
Perhaps this could be adapted into some kind of suitability test for prospective employees. Instead of all those long and complicated interviews, psychological profiles, and adaptability tests, you just need to ask the geek the other side of the desk how many cats they've got. It would work on a sliding scale: one moggy, suitable for general development tasks. Two Seal-point Persians, obviously a prime candidate for program manager. A British Blue and a Cornish Rex, would do well in technical support and systems administration.
Of course, what would be really useful would be to establish if there is some reason for this amazing compatibility situation. While avoiding any puerile reference to mice, what subtle traits do cats and computer programmers share that attracts a woman to both? Is it the inscrutable independence, the haughty view of the world as being there only to satisfy their whims, or the fact that - despite giving every outward appearance of being asleep for 23 hours a day - they are actually alert to everything going on around them? Or maybe it's just that both have an inbuilt sense of independence. I suspect that the term used to describe some hopeless task as being "...as easy as herding cats" might work just as well as "...as easy as herding computers". I mean, how often does your computer do exactly what you expect...?
Meanwhile, I've also discovered that women who like dogs tend to marry plumbers or policemen. OK, so I only know one plumber and one policeman, but we're getting 100% compliance to the rule here as they both have very large dogs.
Every now and then I get to write actual code rather than just documentation. Usually there's either a crowd watching in amazement that I can actually find Visual Studio, never mind knowing some of the magic keywords that make it all work when you press the green arrow button. Or else everyone is cowering behind their desk in case my computer can't cope with the culture shock and explodes. Isn't it wonderful when everyone has so much faith in your capabilities - after all, I've read the .NET Architecture Guide (endlessly, as I've been working on it for the last year) so I ought to know a bit about this stuff.
Unfortunately, as I've rambled about in previous posts (such as "How p&p Makes Cheese Sandwiches"), my programming tasks tend to involve building kludges and "temporary fix" tools to solve problems that are either too esoteric to be of any use to people outside our small documentation team, or are a stop-gap until the proper tool gets upgraded next time. OK, so I used to be a consultant and I wrote a few Web apps for customers, but I'd hesitate to publish "best practice compliance" figures for those. Especially as they were also usually kludges required to get software the company had paid big money for to work how they wanted it to.
So, anyway, last week I decided to put together a rough tool to help us find broken and incorrect links in a documentation set that builds to create a CHM or HxS file. The issue is that, although the authoring tools we use can create links between topics and within topics, you can't easily (or at all in some cases) check if these links are valid. They may point to a topic that you removed, or the target topic may have changed (so has a different auto-generated topic filename), or they may just point to the wrong topic. We do use a link checker utility to find broken links, but it can't find links that go to the wrong topic or links that point to an anchor (bookmark) in the same page that does not exist. The only way we can verify these are through manual testing ("click and read").
In theory, the process for automatically checking the links that the link checker cannot verify sounds relatively simple. Every topic page is an HTML file generated by the documentation tools from the source Word documents. The text of a link that points to a separate topic should have the same text as the title of that topic. And a topic containing an in-page link should contain an anchor that matches the bit after the "#" in the link href. So it's just a matter of applying some processing to each HTML file to verify these rules. I could do it by reading the pages one by one using MSXML, or just open them as text files and read the source that way.
I chose the second approach for no better reason that it seemed easier and quicker to build, and because I already had most of the code from another tool that did similar stuff to update various sections of the source files (such as inserting feedback links and index entries). All it involves is some judicious string handling, searching, and text comparisons. Of course, it got more complex as time went on because I found I needed to allow for optional settings such as allowing the case of titles to differ, and ignoring leading and trailing spaces in topic titles. But it was fairly easy to stir in a mixed selection of semi-appropriate keywords and variables, and bring the whole lot slowly to the boil.
Did I use agile development methods, as I know I should (especially after working with the p&p dev teams for so long)? Well, if you can call throwing it together and fixing broken bits afterwards "agile", then yes. But, in reality, no. I should have started by writing tests, but the tool simply reads the files and dumps the results out as a log file so how do I write tests for that? Probably I should have divided the task into a series of separate routines for each minor action, and written tests for each one, but that seemed overkill for such a simple project. I did all the testing as I went along by adding errors into a set of existing source docs and then checking that each one was detected as I added features to the code.
After it all seemed to be working, confirmed by fairly comprehensive testing by my advisory panel and beta test team (Hi, Nelly), I decided I should do the agile "refactor" thing. Except there was just one chunk of code that got used more than once (twice in fact), and it was only three lines. Perhaps I could write some generalized code routine with half a dozen parameters for some of the functionality, and call it from the three or four places in the code that seemed appropriate. Would that be more efficient than repeating half a dozen lines of code in four places? It would be easier to maintain, but probably take time to code, fix, and retest everything again.
Next, I did the "make it more efficient" thing. One thing the code needs to do for each inter-topic link it finds in every page is extract the title from the linked page (if it exists) to see if it matches the text in the link. First time round, I had a routine that opened the file, located the <title> element, and returned the contents. But this meant I was opening every topic multiple times; for example, every page contains a link to the contents topic so it gets opened and read for every page in the doc set.
Obviously this is hugely inefficient, even if .NET caches the file contents. So, I simply added code to save each title it found in a Dictionary using the file name as the key, and then look in the Dictionary before reading the disk file. That way the code only opens and reads each topic page once. Makes sense, but when I ran the code again it made almost no difference. I did some comparative tests, and the reduction in time taken to process the doc set was averaging somewhere around 5%. And as the tool, running on a fairly average desktop machine, can process a doc set containing 465 HTML topic files in less than 5 seconds, how much time and effort should I put into fine tuning the code? Especially as you only run the tool a few times at the end of a project after the docs are complete and you are ready to build into a CHM or HxS...
Don't get me wrong, I'm not in any way suggesting you should ignore the principles of coding best practice, agile development and pre-written tests, and proper pre-release validation. But, sometimes, just getting stuff done by relying on the power of modern machines and software environments does seem appropriate. Though I guess I'm not likely to get any jobs building "proper" enterprise applications now I've 'fessed up...