Random Disconnected Diatribes of a p&p Documentation Engineer
Oh dear, could it be that my brief career as a documentation engineer is about to come to an abrupt and unexpected end? Has my recent sin been so dreadful that I will be thoughtlessly cast aside, and once again reduced to wandering aimlessly around conference circuits and local dev shops with all my worldly goods in a shopping cart, trying to scratch a living by talking and writing about enterprise software architecture? Next time you see a sad and lonely figure dressed in a grubby (but geeky) T-shirt and scruffy jeans, clutching the tattered remains of a book on design patterns in one hand and a seriously out-of-date laptop in the other, spare a thought - it might be me.
What was my dreadful sin? Well, in a recent article I used a rather too well-known abbreviation in the section that encouraged potential users to carefully study the documentation provided with the product before using it. And I nearly managed to sneak it past my editor, the policy checking people, and the entire legal team. But they caught up with me in the end. It seems, as a colleague explained, that they "have something against the letter F". Of course, I immediately took steps to ensure that we as a team never make that mistake again by sending them all an urgent email:
IMPORTANT NOTICE TO ALL STA:Please be aware that, in uture we need to be ully aware o company policies and careully avoid any oending letters.
Thankfully, and perhaps in part due to my prompt action, it looks like we've all escaped with just a slap on the wrist this time. OK, so I have to sit in the corner with a pointy hat on, and I'm not allowed any of those fancy p&p cheese sandwiches for a week, but it could have been worse. Especially if they'd known about my other recent word crime. And this was one that you can very easily commit.
Imagine you're answering an email from someone asking about your new product. You reply in an encouraging "please buy it" way with something like: "The new Abracadabra Mark 2 is reliable, robust, and secure." No problem? Well, what if your customer buys one and it falls over the first week (reliable?), dies the second week when someone presses the wrong key (robust?), and finally suffers a successful attack from an intruder in week three (secure?). Yep, you should have said "designed to be reliable, robust, and secure", because - no matter how hard you try and how well you design it - nothing is ever going to be absolute. It's so easy to slip up when you're bashing out a quick email, but at least now you've been warned. Luckily my email never actually reached the "clicked Send" point...
And, talking of email, if you'd been here last week by the server rack in my garage in the windswept and rainy (but strikingly beautiful) Derbyshire Dales, you'd have seen me jumping up and down like a cheer-leader, and whooping like a supporter at a presidential rally. Why? Well, stepping back a bit, it's all to do with "Unsolicited Commercial Email" (and isn't that a great acronym for junk email? I once wrote an article that was fairly iffy, but had the wonderful title "Spam Filtering - Is It Any UCE?").
Anyway, I've been using the same personal email address for about 10 years, it's on every spam list out there, and so I get tons of junk email every day. I now use an outsourced email filtering service to control it, and they bounce something like 1200 spam messages per day (yes, per day) that are sent to random and non-existent names at my domain. Some spam does still get through, but not enough to be an issue. And with the money from all the lotteries I've won, the profit on my Nigerian Oil Company shares, and the commission for handling the legacy of the recently deceased King Alibongo, I'll soon be able to afford one of those brand new Rolex watches anyway.
But the emails that really annoy me are those System Administrator messages informing you that "...your email offering Valium and male enhancement services could not be delivered to one or more recipients". Of course, when you examine the original message headers, it clearly didn't come from you at all - it came from somebody who spoofed your email address (assuming that your mail server is properly secured and you haven't been botted). Even more annoying, the Non-Delivery Report (NDR) says that "...delivery will be reattempted over the next three days." And it's absolutely pointless getting worked up and shouting "No, don't bother, just forget it!" at your mail server, because that's not where the message is coming from.
So, a couple of years ago, I went to all the trouble of learning about Sender ID / Sender Policy Framework (SPF) in the hope that it would fix the woefully inadequate Simple Mail Transfer Protocol (SMTP) that we seem to be stuck with. I figured it out, created the appropriate text string for all my domains, and inserted the records into my DNS servers. And, to be perfectly honest, it seemed to do pretty much nothing - until last week when I opened an NDR from Google and found this:
Delivery to the following recipient has been delayed: email@example.com
And, there amongst the message headers, was:
Received-SPF: fail (gmail.com: domain of firstname.lastname@example.org does not designate 126.96.36.199 as permitted sender);
Wow, they actually checked my SPF records and bounced the email because they knew it wasn't from me - it had a spoofed "From" address! At last all that effort was worthwhile. But further down the message it said: "...delivery will be reattempted over the next three days." And you thought I was the one who sent stupid email messages...
I suppose I could try to impress people by telling them how I spent a pleasurable evening at a concert at the Buxton Opera House a week or so ago. But as I don't have any posh friends, and only a few posh colleagues, I guess it's safe to admit that the trip was actually to renew an infatuation from my younger days. No, honestly, it's safe to read on. I promise not to descend into tales of a depraved, wanton, and wasted youth (though I wish I'd had one).
The infatuee in this case is the fabulous Toyah - whose weird and wonderful style fascinated so many young men of my generation. Was it the mass of spiky orange hair? Was it the strange mechanical gyrations? Maybe it was the incredible wandering vocal style? Or just the fact that she was (and still is) gorgeous? And this revisitation to my adolescent infatuations was, in fact, my wife's fault. She saw that Toyah was guest-starring on the latest Vampires Rock tour, and graciously agreed to let me go and see her again after something like 30 years.
So I was spared seeing opera, and instead saw an incredible show. If you get a chance (and you are into rock music), go and see this - or buy the DVD. It's the best night I've had for ages. The live band is superb, as is the scenery, lighting, effects, cast, and pretty much everything else. It's even got comedy, lots of (stage) blood and gore, and Emily Clark (who plays Pandora) has the most amazing voice. She does Suzi Quattro as good as Suzi Quattro, and "Total Eclipse of the Heart" very nearly as well as Bonnie Tyler. Just don't expect too much of a story...
And, yes, Toyah was as wonderful as ever. Still as exciting to watch, and she still has a fabulous voice. It's just a shame she didn't get to do "It's a Mystery" or "Angels and Demons". Best of all, though, she is just as weird as she was thirty years ago. In fact she admitted in a recent TV interview that, after doing the Gobi desert "Great Walk to Beijing" with Danni Minogue, Danni had said that "Toyah was the maddest person she knew".
But enough trivia. What continues to surprise me is how the technical management of shows like this is so bound up in computerized technology these days. When I was still at school, it was blatantly clear to all that I couldn't sing, act, remember lines, or look anything other than odd and geeky. So I never got a role in a school play. But I could build stuff like bubble machines and disco lighting gizmos (all driven by relays, cams, and zonking big washing machine motors in those days) so - together with some friends - we were in charge of the "effects" for plays and concerts.
It took three of us to do thunder and lightning (with a tape recorder, dustbin lids, and a couple of spotlights), and five to untangle the microphone wires at the end of each act. And trying to get the right music and sound effects to occur at the right times was a massive feat of engineering involving 8-track cartridge players, BBC "Sounds Off" LPs, and large volumes of sheer luck.
Now, it seems, they just press a button and the whole concert happens. I watched them testing some of the settings on the control deck. Or, rather, I watched one guy clicking the mouse a few times. The whole show, including sounds, lighting, effects, fireworks, and even the scripts and timings, are preset in some fancy Windows application. I guess it's just the natural progress of technology into all walks of life, but I wonder if it takes away some of the magic of theatre?
Still, it will take something special to surpass the sight and sound of Luke Morley strutting across the front of the stage with blood running between his fangs while playing Slash's lead riff from "Sweet Child of Mine"...
I love how the Visual Studio Document Explorer (help viewer) has a topic named "Help on Help". I've often wondered whether it should say "Help Upon Help", like there was several layers piled up on top of each other. Or how, if you can't figure out how to use the Help file, a help topic within it would be useful. Still, I suppose it's better than the old days when you had help items such as "The Range property sets or returns the range" and "To close the window, click the Close button".
But if your responsibilities include the creation of help sections for Document Explorer (as mine do on a regular basis), you'll know how fiddly it is to get the right stuff to appear in the right place, at the right time, and with a matching index. I suppose help-generation tools have never really been cutting edge, although there are some good third-party tools out there. And, of course, we have our own p&p Doc Tools to help us create the content. But it's the "massaging it all into a merge module" thing that has blood-boiling capabilities.
Of course, you can create Help files using Visual Studio itself - if you can figure out the instructions in the help file, or even find the appropriate section. Here's a clue: you'll need to install the Visual Studio SDK and then find the topic Visual Studio SDK | Visual Studio Development Environment SDK | User Interfaces | Help Authoring and Integration | Help Authoring | Getting Started with Help Content and Integration. I guess that shows how important help authoring actually is...
Anyway, as usual, I'm here to offer some useful nuggets of assistance (no laughing at the back please). Building a merge module for DocExplorer involves three stages: build the HxS and associated content files (TOC, index, etc.), use the VS Help Integration Wizard to compile these files into a merge module, and then test the merge module in DocExplorer by using a VS Setup project to install it. In our case, the p&p Doc Tools create the HxS and the other input files, though you can do this using other tools. Where I encountered problems was the conversion into a merge module.
The issue is that, as the dev team builds stuff, they like to do regular CTP releases so that people can see where they are going and provide feedback (and, dare I venture to say, help them find the bugs). So our help docs get compiled into merge modules at regular stages. Each release has to have the correct headers, release dates, pre-release text, and internal namespace (each merge module is identified by a unique namespace). These details are specified in a combination of ways in both the input HxS files and in the VS merge module project.
To build the merge module, you run the VS Help Integration Wizard. It collects all the information it needs to build a "plug-in node" (the root node of the set of help files in the Doc Explorer TOC), and then assembles all the files so that VS will merge the contents correctly into the existing sections of DocExplorer. The problem is that, despite spending many hours on many occasions searching, I can't find any way to re-run the Wizard when I want to change the settings.
So, I thought, no problem. The input files are mainly XML so I can edit them. However, Windows is clever. I naively assumed that searching from Windows Explorer for files containing the text I wanted (such as the release date) would locate all the files I needed to edit. What I forgot was that the search feature only searches the contents of file types it knows about. Give it a mass of files with extensions like HxF and HxK and it simply turns its nose up in a kind of "you don't really expect me to look inside there, do you?" way. So I never could figure which files I needed to edit.
But then, with the latest project, I decided I was going to solve the problem and used a "proper" search tool (actually TextPad, but don't tell anybody). Bingo! (or "Eureka" if you are posh). After some experimentation I'd found all the places that you need to change stuff. After that, I recompiled the merge module, recompiled the setup project, installed the merge module into Doc Explorer, and it worked. No need to nuke the merge module and setup projects and start over each time. Here's some pointers that might help:
<MSHelp:Attr Name="DocSet" Value="MyCTP1Docs" />
"%CommonProgramFiles%\Microsoft Shared\Help 9\dexplore.exe" /helpcol ms-help://MS.VSCC.v90/MS.VSIPCC.v90/[your-docset-namespace] /LaunchFKeywordTopic [keyword-in-target-page] /filter "your-filter-description"
<MSHelp:Keyword Index="F" Term="mycompany.myproject.yearmonth.introduction" />
As a side note, when you do test installs of merge modules, I'd sincerely recommend using a VPC with Visual Studio installed, but not much else. The merge process happens automatically when you open DocExplorer after installing a new merge module, and it can take ages if you have lots of other merge modules (lots of help topics from lots of other installed products). Using a VPC means you can test the installation, then abandon (delete) the changes to the VPC so you don't have to uninstall the merge module again.
If you don't use a VPC, remember to open DocExplorer and then close it again before you install the merge module to ensure that there are no other merge changes pending. And after you uninstall a merge module, make sure you open DocExplorer again to let it sort itself out - it remerges all the remaining content again. If you uninstall and then reinstall a merge module without allowing it to remerge, you may well see the old module content instead of the new content unless you changed the namespace in between.
Or just give users the original Word documents and let them print out their own help file...
Maybe I've been asleep for the last few months, or just head-down working on my current project, but it seems I am the only person in the world who wasn't aware that a new version of Windows was on the way. Well, the only geek anyway. I don't mean the "Mojave" stunt - I mean what is currently referred to only as "Windows 7". And, rather strangely, my first thought when I read about it in a UK computer magazine was "Wow! Has there only been two and nine-tenths other versions since the Windows 3.1 that we all knew and loved?" That introduction to millions of the Windows world of GUI seems so long ago now...
Other stuff that followed closely in terms of mind-springing was probably even less the kind of thing that the marketing department would hope for. I couldn't help seeing misty visions from the past of the Austin 7 and, of course, Blake's 7. But no doubt there is already a selection of swish names being brain-stormed in the palatial offices of the "Let's get out there and sell it!" brigade. Seeing as everything these days is "Web 2.0" and "Community-driven", maybe they'll hold a competition and let the winner choose a name. I'd be no good at that. I could never figure why they called Vista "Vista" (if you see what I mean). I thought it meant "Goodbye until we meet again", as in the film Terminator, until I discovered that the "Vista" bit means "seeing". I guess that makes sense because my Vista laptop is the first one I've ever had with a built-in camera (even if there aren't any Vista drivers available than can make it work).
So, anyway, this computer magazine asked users what they wanted to see in Windows 7, and one of the top answers was support for the local culture and language. Yes, they mean "proper" English with all the missing letters reinstated or changed round into the correct order. They want a "Favourites" menu and a "Security Centre". And maybe even the Queen's English as well - how about: "One is asked to wait patiently during the processing of the current request...". I suppose that would mean they'd need to make all the dialogs bigger, but it would be rather nice to have a polite computer. "Excuse me, but it does seem as though there is a recently-arrived email message awaiting one's prompt attention."
Of course, it wouldn't stop there. I mean, doesn't anybody else realize that there is no such country as "UK"? England is a country, as is Wales, Scotland (and, I guess, is Northern Ireland). Yes, there used to be a "United Kingdom" (about 300 years ago), but now that the Scots have got themselves devoluted, and the Welsh are part-way there, it's hard to see how we are still "United". I, as thousands of other people do, refer to my country by its real name - even to the extent of chancing my luck at U.S. Immigration by putting "England" on my visa waiver form!
Wandering off topic, it seems that Wales is actually a new standard measure of area. When you want to amaze people with how big something is, such as the size of an Australian sheep ranch or the area covered by Lake Superior, you quote it as multiples of the size of Wales. As in "Did you know that Lake Superior is four times the size of Wales?" Don't believe me? See sizeofwales.co.uk.
The other option, which I can live with, is "Great Britain". I like the sound of the "Great" bit, even if we aren't really that important in world terms these days, and it's handy for doing TV programs and stuff like a list of the "Great Britons" of history. And, of course, we do have our own language/culture code "en-gb" which just goes to reinforce this (so, Windows dev guys, you ain't got an excuse for missing us out). Maybe to save confusion they could incorporate the culture code and call it "Engblish" instead?
And if "gb" is the accepted term for Great Britain, when are all the Web sites in the world going to fix their address entry list boxes? If they can't be bothered listing all the countries, we should at least be "Great Britain" instead of "UK". I mean, they list other countries using the proper name, or at least a translation of it. The culture code for Spain is "es" for "España". And I'm sure that China isn't called "China" in Chinese (why would it have the culture code "zh" if it was?). OK, so I could look it up, but I probably don't have the right keys on my machine to type it here anyway. Oh, and while we're talking about China, did anyone realize that the number 7 in China is supposedly related to anger and abandonment...? (see Travel China Guide.com).
Still, I suppose the "name of my bit of the world" thing happens on a smaller scale as well. Here in Engbland, many years ago, they decided to steal lumps of East Yorkshire and Lincolnshire and rename them North Humberside and South Humberside. The rumour at the time was that the Government needed to justify building a bridge that cost hundreds of millions and went from a major coastal city to nowhere in particular (or maybe the posh folk in the East Riding of Yorkshire just wanted rid of Kingston-upon-Hull). Of course, nobody took any notice and kept writing their address as "Yorkshire" or "Lincolnshire". After a while, South Humberside got renamed again to "North Lincolnshire". I wonder how much money all that wasted?
And now, horror upon horror, they want to move Lowestoft from Suffolk into Norfolk. I assume they mean moving the county boundaries, not actually packing the town in boxes and loading it onto a big truck. Question is, will the genteel people of Norfolk be able to cope with a town so famous for being the place that created "The Darkness"..? Come back Justin, we want more.