Random Disconnected Diatribes of a p&p Documentation Engineer
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" />
<Query>"DocSet"="MyCTP1Docs"</Query>
"%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"
[your-docset-namespace]
[keyword-in-target-page]
<MSHelp:Keyword Index="F" Term="mycompany.myproject.yearmonth.introduction" />
"your-filter-description"
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.
Here in England, architects (the kind who design houses and office blocks) seem to have a pretty poor reputation. Other than the "stars" who win prizes for designing skyscrapers, or weird shopping centers that look like an armadillo that wandered into a chrome-plating factory, they seem to be universally reviled. Perhaps it’s the same in the US. I remember once hearing the quip "Don't tell my mother I'm an architect, she thinks I play piano in a whorehouse". That sounds like a US-ism if you ask me.
We have a TV show named "Grand Designs" where people with huge ideas and equally huge piles of spare cash build strange houses. While all the houses are very different, all the shows have some things in common: it always costs more than they budget, it always takes longer than they planned, and they always fall out with the architect. Somehow you just know that the cantilevered roof won't pass building inspection, the windows won't fit, the kitchen will be totally impractical, and the rain and snow will ruin the exposed timber beams before the roof tiles arrive (though maybe you can't actually blame the architect for that).
The only show I can recall where it all went right was a young couple who bought an old pumping station for about £5 ($10), made a fortune selling the pipes and tanks for scrap, did all the work themselves over a two year period, and turned it into the most fabulous place with a lounge area so big they used a cut-down Mini car as a desk - and you didn't notice it till they pointed it out. Strangely, the house is only a few miles away from me, but when they sold it, the price was the equivalent of a million dollars US. Somewhat out of my reach unfortunately. Shame, I could probably have parked my car in the bathroom to wash it.
So, anyway, I wonder if software architects face the same problem. Do developers stand back from some complex business layer component and mutter "We'll have to chop some lines of code off that if you want it to fit into the server...", or "That data access layer will fall over the first time we get a decent breath of wind blowing off the hills...". Maybe the administrator goes off in a huff mumbling "Typical architect, never specified a long enough piece of HTTP to connect the Web server to the database server...". And the project manager is left to give you the bad news that the event handlers the architect specified are only available from one factory in Sweden, and they are closed for the holidays.
As an aside, it's actually illegal in the UK, according to section 20(1) of the Architects Act of 1997, to use the term "architect" in your job title if you don't have "appropriate" qualifications (see Regulation of Title). Though the Architect's Regulation Board seems a bit more relaxed about it these days. But I did hear that at one time they were trying to enforce this and make software people use something like "Software Designer" instead. What they probably meant was "Jumped up geek who does stuff with computers..."
Of course, in building houses terms, the architect is probably long gone when it all goes wrong, or is protected by something in the vast wad of small print. But I suppose you have to feel sorry for them. I mean, in terms of software projects, I never heard yet of one where the delays, bugs, lack of performance, or cost over-run were blamed on the architect. It always seems to be the developers fault. So guys, here's your answer. Lean back in your chair, suck your teeth and make that "not-my-fault" whistling sound. Then explain to the project manager that it's all the architect's fault. He designed it, you only built it...
And maybe add that you couldn't get the right bits...
(OK, need a good, hard-hitting, gritty opening sentence this week to get people interested. Here we go...). Last week I went shopping. (Hmmm... not quite the impact I wanted, but press on regardless). I wanted a new battery for my camera, so I popped into a local specialist. "Hi," I said breezily, "I need a battery for an Olympus 1010 Stylus camera". "OK," replied the obviously knowledgeable young man behind the counter, "just fill in this form". He presented me with a long form where I had to enter my name, address, credit card details, and a myriad other details. Finally, when I gave it back to him, he said "Right. We don't actually have one in stock just now, but it should be here in a couple of weeks". Needless to say, I tore up the form and stormed out in disgust.
Across the road, I noticed a rather interesting looking computer store, and decided to have a wander round. After about half an hour, I'd filled my shopping basket with a dozen or so items, and sauntered over to the checkout. Suddenly, a rather aggressive looking lady took my basket off me and disappeared. After a few minutes she returned and gave me back an empty basket, explaining that there was a problem with the cash register, but I was welcome to go round the store again and refill the basket. I decided not to bother.
Somewhat irritated with the day's events, I thought I'd calm my temper with a cup of coffee and half an hour with my newspaper. A few doors down the street I found a nice coffee shop, though I was more than a little perturbed to see a sign on the door that read "Warning: for your safety you should only enter these premises wearing a red satin waistcoat and brown leather shoes". Now, red doesn't go with my complexion, and I don't own any brown shoes, but I decided it was worth the risk. However, I did ask the pleasant young lady behind the counter if I could see the manager to complain about this blatant discrimination. She replied that I had to tell her the password before I could speak to her boss. "How can I find out what the password is?" I asked. "I don't know", she replied, "He always keeps it in a sealed envelope in his pocket".
Deciding that drinking coffee here was perhaps beyond my risk threshold, I left and strolled across to a large branch of a national well-known supermarket chain. There I had a nice cup of coffee in their restaurant, wandered round and collected all the stuff I needed, was greeted by a helpful and efficient checkout operative, and was on my way home in no time.
Of course, you will probably have guessed (if you are brave enough to have stuck with it this far) that the preceding is all a huge fabrication. Or, at least, it's partly a fabrication - and may just serve to indicate how stupid things can get in our modern, high-tech, shop-on-line society. In fact, last week I did...
It does seem strange that, after more than ten years, we still seem to be struggling to provide an Internet that works reliably, works in all browsers for all users, and actually makes life easier. People even seem to spend more time worrying about how that CSS border line is "two pixels off", and that some browsers don't "fully support all the standards". It's not hard to see why the big boys in this game continue to grow, while so many others fall by the wayside. OK, so it is hard to get right, especially for small sites with limited resources. Perhaps the answer does lie "in the cloud" with "Software plus Services" (S+S).
So would you trust some outside organization to provide all the services your business (or hobby Web site) needs? In my previous life as a creator of retail software and purveyor of IT services, I always said that I would provide my own infrastructure and services to make sure it did what I wanted, was always available, was secure, and was under my control. I run my own Exchange Server, public DNS, and Web sites. Yet, looking at my systems, I was surprised to see how much I already outsource. Before becoming a 'Softie, I used Powernet to filter my incoming email. I used LunarPages to host large file downloads and one of my Web sites. I used DigitalRiver to take orders and process payments for my software products. And this blog is hosted on MSDN. One of my colleagues even uses an online source code repository and an online backup facility.
I guess when you think about it, it's hard to see why anyone would start now to create a new general-purpose search engine site to compete with the few guys who already own the market. Why would anyone want to build a new auction site, when it's so easy to use EBay and the like? And small retailers seem to be congregating in their thousands around the in-store shopping services available from Amazon and others. Maybe the future is a relatively small number of "in-cloud" service suppliers, with the majority of sites hosted there.
But why "cloud"? In his blog post "Can We Please Define Cloud Computing?" (which presents some interesting views of the topic) Mark Hopkins mentions that the first time he saw the use of of the cloud symbol was in diagrams of MCI's ATM router mechanism. I remember way back when we were writing our first Internet books (about Internet Explorer 3) at Wrox Press we decided to use a cloud symbol to represent the Internet in our schematics - it seemed the obvious choice and represented stuff that was "going somewhere else, but not sure how". Isn't it amazing how a whole technology can get its name from a PowerPoint shape...
At last I can document something that might, possibly, be of marginal use to those one or two readers who mistakenly stray into the quagmire of my unrelated weekly ramblings. For the last few months I've been fulfilling my new role as an out-of-sight-and-out-of-mind remote documentation engineer (that's a documentation engineer who's remote, not an engineer who writes remote documentation - though, having read some of my scribblings, you might dispute that assertion). Anyway, recently I was beamed up to the mother-ship to spend a couple of weeks onsite at Redmond. I suspect they just wanted to see if the weird English guy they accidently offered a job to actually does exist.
So a while ago, while preparing my shiny and tiny XPS laptop for the trip, I had a minor moan about Vista's backup facility. But little did I realize that worse was coming my way. My laptop usually lives on the corporate domain, even though I only connect to the domain over a VPN and am not connected during login to the machine. The cached domain credentials allow me to log into the machine without being connected, and then the O/S authenticates me on the domain when I connect to the network.
All fine so far. Except that, for some reason, one day it suddenly stopped me from logging in to the machine. I assumed that this was because I hadn't physically connected to the domain for several weeks. So it should all sort itself out when I can reduce the 5,000 mile gap between my laptop and the nearest corporate Ethernet socket. The domain controller would be forced to accept that I'm not just some ethereal figment of its Active Directory, and would gleefully welcome home it's long-lost prodigal son.
Now, I'm not generally known to suffer from wild spasms of optimism. And so I wasn't really surprised when the long-awaited fusing of my tiny little Dell with the corporate big-iron simply resulted in an Event Viewer full of error messages, a pop-up telling me there was an error in my profile, and the machine refusing to persist any changes to the environment. Every logon was accompanied by a long wait while Vista "prepared my desktop" (I could have built a whole desk in the time it takes), a task bar full of useless notification icons (what the **** do they all do?), dialogs welcoming me to the exciting world of Windows Vista (yes please, I'd love to watch the introduction video again), the Home page of Dell Support's Web site (just in case something broke while booting up?), and - of course - none of the useful stuff I set up last time.
After a quick consultation with the onsite server admin guy (hi Mike), it seemed like this is not an unknown issue - he had a laptop suffering from just this malady. While he hadn't had time to investigate, he did confirm that it was a problem with Vista not being able to create the profile folder on the local disk. But why? The relevant folder did not exist, the parent folder was not read-only, and a quick test by manually creating the required folder had no effect. So it looked like I was in for another of my regular hunt-round-the-Registry-and-delete-stuff exercises.
Of course, as per accepted administrative guidelines, I need to warn you about editing the Registry. So, before you start, make sure you write out your will, lay in supplies of pizza and cola, and say goodbye to the kids and the dog. You might also like to wear some protective clothing (a T-shirt with a suitably inane slogan will do), and make sure there is nothing valuable in the direction you are likely to throw the unbootable machine afterwards.
Once prepared, locate the Registry Key:HKEY_LOCAL_MACHINE \SOFTWARE \Microsoft \Windows NT \CurrentVersion \ProfileListThis contains a subkey named with a SID for each user account on the machine. In theory, there is one for each of the named folders in the C:\Users folder on your disk. If you select a SID subkey, you'll see the user name in its subkeys, so you can compare each one with the disk folders. You should find ones for the Administrator, Local System, and Network accounts; as well as ones for all the users registered on the machine or in the domains you've joined.
My machine has led a busy existence during its short life, moving between three domains and having a couple of local users. During a "routine clean up", I seem to remember deleting some of the subfolders in the Users folder - though I was, of course, careful not to delete any currently registered users. What I discovered was the Registry still held references to profile folders for accounts that no longer exist on the machine, but not one for the domain account I was trying to use. I have no idea why this caused a problem, but I decided to tidy up the Registry while I was in there and deleted the SID subkeys, including all their child subkeys, for all of the non-existent user accounts.
Then, having decided which wall would be the target for an airborne laptop, I rebooted. And, magically, it all worked. Instant logon to the domain, wireless certificates downloaded and installed, and no errors. Quick reconfigure of the desktop, log off, log on again, and it remembered my settings. No more "Welcome to Vista" stuff; and everything working just as it should. Even Outlook managed to find its Exchange Server without the usual application of a large stick. Amazing. Maybe I can actually get to love Vista after all...
They probably won't invite me over to Redmond again. After telling me for weeks about the wonderful summer weather there, it rained for most of the two weeks I was on site. Not many people would suggest that I have a magnetic personality, but it sure looks like the English weather followed me across the pond. We even had hail one day (in the middle of August), followed by a small tornado. And I'd taken shorts and sun cream with me. But I suppose after it rained almost the whole time during my last two trips, I should expect it. Maybe I can earn a few dollars extra by selling people my travel plans so they can plan their holidays around my trips to Redmond.
Mind you, Washington State is one of the most beautiful places I've ever been to, and it wouldn't be lush and green without the rain. And, by some extreme good fortune, the two days when the sun did shine I was treated to a boat trip round Lake Union and Lake Washington (we waved to Bill, but he didn't invite us in for tea); and a trip to see Snoqualmie Falls (absolutely amazing!) and the Northwest Railway Museum (they obviously read my blog where I confessed to being a railway enthusiast). Though I had to laugh when a colleague said how she'd told her friend that I was a train spotter, and her friend was horrified - "What?", she said, "You mean like in that awful film...?"
So the nice-weatherness was a great deal less than I expected, yet the breathtakingness of the falls was substantially more than expected. But that's how life works. Sometimes you get more than you expect, and just as often you get less. In fact, only last week my wife told me about how one of the girls who works in her office was complaining after going to see "Mamma Mia" that the film was full of Abba songs. She doesn't like Abba...
Here in the little office in England where I engineer documentation for p&p, expectation is something that constantly raises its ugly head. What do people actually want or need in terms of guidance when they install a product such as Enterprise Library or read the Web Services Security Guide? As you'd expect, we go to considerable lengths to collect feedback from focus groups consisting of specialists, customers, and industry leaders; from satisfaction surveys; as well as through in-house reviews and direct feedback from documentation links and CodePlex forums. And, in general, the results are encouraging. In the past, in some software companies, it seems to have been the case that the code was king and the documentation an afterthought. But, generally that's changed as companies realize that users expect more. And, let's face it, as the sole purpose of my job is to create guidance rather than code, what people expect has got to be a major focus.
But what exactly do customers expect from documentation and guidance? While there is never going to be a single answer, getting it right should give the maximum help to the most people. One of the things we are working to achieve is to provide a range of documentation on architectural and pattern-based topics that suits the wide range of consumers. That means everything from introductory "Getting Started" topics to reference documentation such as API references, key scenarios, and checklists.
And, of course, there are different formats. Videos are a great way to introduce technologies and practices, and to show development stages and techniques. But they can be limited in reach due to bandwidth limitations and the time commitments required both to create them and to watch them. Slide decks are also useful, but without a commentary like you'd get at a conference presentation, it's often hard to get real depth with just bullet points and schematics. Ideally, you would sit down with an expert in the technology who could explain it all to you and answer your questions. Microsoft do just this through summits, conferences, and their evangelism groups, but unfortunately we don't have enough staff in p&p to provide every developer with their own personal trainer.
In the end, the major source of information has to be the written word; as a help file, Web pages, a white paper, a PDF, or a printed book. We need to explain scope, concepts, objectives, scenarios, and details. The guidance should work for relative beginners, skilled developers, technology experts, and software architects. And for each group it must be set at a suitable technical level, and written using the appropriate terminology. It also needs to be localizable into a number of different languages.
And here we run into one of the major issues we're trying hard to tackle. Microsoft publishes a style guide for documentation (it's the bane of my life sometimes) that specifies in excruciating detail exactly which words you can use, how to phrase them, and how to construct the required grammatical content. This helps to avoid confusion, provides standardization across products, gives a common appearance that developers recognize, suits different cultures, and works with automatic translation tools. So the tone and style of the documentation is pretty strictly controlled.
However, at the same time, there's an increasing feeling that our documentation should be more "approachable", "personable", and "entertaining" - and even, shock, horror, "exciting". I'm not sure exactly how exciting you can make a table describing the methods that resolve objects in Unity - maybe throw in a few bad puns like "...the object of this method..." or "...you should resolve to use this method when...". As to exciting, how about "When you click this button, something will happen ... perhaps ... why not try it and see...?".
But, seriously, how do you decide where to pitch the level of the content? Would something lively with a few jokes thrown in make learning easier? How much would this style grate after a while? Should we use the "we apostrophe" approach instead of the "you formal" style (for example, "Now we'll add a handler to validate input data" rather than "Now you will add a handler that validates input data")? And would jokes made up by some semi-deranged Englishman (me) seem funny to people in other countries? I told the joke about the golfers to a colleague before I published last week's INAG article and he had no idea what I was talking about - I had to explain it to him. And he was from the US. So much for us sharing a common culture.
Maybe, instead, we should just continue to publish a range of guidance aimed at different levels of developer/architect and at different levels of product complexity. For example, "Getting Started" guides that compare features to common household objects and situations (like the "Getting Started" articles linked from the p&p Home page) as well as high-level bullet-point technical feature reviews for architects to use when planning major projects. And, alongside, reference-style documentation like that we produce now for Enterprise Library and similar products. Let me know what you want to see - I'm open to suggestions...
Meanwhile, by some strange coincidence, I had previously been ruminating about guidance phrasing while sitting in the departure lounge at Amsterdam airport for several hours on my way out to Redmond. You know what it's like. After a couple of hours you have read all the warning and information signs, counted the ceiling tiles (twice, just in case you got the total wrong the first time), given up trying to decipher the language the two people behind you are speaking, and started reading your food. In my case, the food was a bag of potato crisps/chips made by a company I'd never heard of before: Sirhowey Valley Foods of Gwent in Wales.
Now these guys make serious crisps and chips, and are proud to say so. The front of their packets talks about how they make their chips using real onions and mature Cheddar cheese, and how they definitely would never cut corners. Then, on the back, the packet has the usual "If you are not completely satisfied..." bit. Except theirs says:
"Although all our chips are made with the finest natural ingredients, some may contain traces of corners. If in the unlikely event a packet does contain any corners, please do not hesitate to send the packet and contents back to us. Don't forget to enclose the offending corners. We would also be interested to see any spare photos from your holiday, if you have some." (see http://www.realcrisps.com/REAL-(Potato-Chips)/REAL-Words.html)
Maybe this is the way forward. We can describe how hard our people work creating the code and documentation. The endless hours and countless pizzas, and how they only pause to wipe the rivers of sweat from their keyboards. And how they ruthlessly test almost to destruction the code and documentation, until it begs for mercy and crawls exhausted into the MSI.
Then on the last page of the documentation we would add our "If you are not completely satisfied..." message:
"Although our documentation undergoes rigorous editing and testing, some may contain traces of bad jokes, pointless puns, and unsuccessful attempts at humor. If, in the unlikely event a guidance item does contain a combination of such words, please do not hesitate to translate it into a different language and see if it is still funny. We cannot be held liable for damage caused by spilled coffee or rapidly expelled particles of pizza. Also note that persons of nervous disposition should avoid reading any sections of the documentation denoted by a "This part may be exciting" warning label."
And please don't send your spare holiday photos to us....
I thought I’d better start off this week with that well-known email disclaimer "INAG" (I’m Not A Golfer). Mind you, when I was a lot younger and fitter, I did occasionally caddy for a few affluent visitors to the R.A.F. Changi course in Singapore. Though when I say "caddy", what I actually mean is "carry the bag and look for lost balls", but you get the drift.
Anyway, the story goes that two of these affluent golfers were walking down the third fairway one day when one said to the other "I hear that John has bought another set of golf clubs." "Really", replied the second golfer, "TaylorMade? Wilson? Dunlop?" "No", said the first, "St. Andrews, Augusta National, and Royal Troon."
Sorry about that ... but isn’t it a strange coincidence how much golf is similar to developing software. They both involve a very limited start location, provide various ways to progress, and have an extremely hard to reach destination.
I mean, for a golfer, you can start each hole from anywhere you like as long as it’s within a patch of grass about 4 yards square. For the software developer, you start with whatever system the customer is running. If you are lucky, it will be some reasonably modern hardware, a reasonably up to date operating system, and a database that is at least contemporary with modern thinking. If you are unlucky, you’ll start in 1980. It will be an old lump of big-iron and a database that uses text files with fixed width fields ("...and can you make it do Web services please...?").
As to progressing towards the target, thoughtful golf course designers generally provided a range of routes that include plenty of rough, some out of bounds if you're lucky, and usually a nice selection of bunkers. In fact, one guy I used to caddy for never once ended up at the green with the same ball he started the hole with, and religiously navigated via each of the bunkers in turn. We sometimes had to come back the next day to finish the round.
Likewise the software developer has a vast range of tools, development environments, software frameworks, and languages to choose from. Mind you, for the golfer, the rough and the bunkers are generally in the same place when they come back next month, next year, or even five years later. This is, of course, unheard of for the developer. They’ll be lucky if the software, tools, and languages are the same next week. In a year’s time they will be "legacy", and in five years time they will be obsolete.
Then there’s the target. OK so it can be tough for golfers. Course managers have a habit of moving the pin around, so the player may have to exert extraordinary powers of observation by standing on the edge of the green and scanning up to 20 degrees left and right to find the large pole with a flag nailed to the top. But it only takes half a dozen putts to get the ball into that little white cup, and you know that you are there.
However, developers probably never even get to see the hole at all. Effectively arriving at the green with a prototype, they are likely to be greeted with "Why does this button do that?" "How do I tell if a customer has paid their last bill when I'm entering an order?" "Three of our operators are allergic to Arial font." or even "Why does it keep asking me to enter a customer order? We asked for a stock control system".
Maybe we should all investigate taking up golf as a profession instead...
I was party to a discussion a couple of weeks ago that wandered off topic (as so many I'm involved in seem to do) into the concepts of whether a programmer is actually "OO" or not. I guess I have to admit to being a long-time railway (railroad) fanatic - an unfortunate tendency that has even, in the past, extended to model railways. So in real life (?),"OO" is the gauge of a model railway. But then someone suggested that many programmers, especially those coming from scripting languages such as classic ASP, are more "OB" than "OO". It turns out that what they mean, I'm given to understand, is that a large proportion of programmers write code that is object-based rather than object-oriented.
I suppose that I've generally fallen into the "OB" category. Having proudly mastered using objects in my code (starting, I guess, with stuff like FileSystemObject in ASP), it was kind of disappointing to realize that I'm still a second-class citizen in the brave new world of modern programming languages. I mean, when I use Visual Basic in .NET I purposely avoid importing the VB compatibility assembly, and I use "proper" methods such as Substring and IndexOf rather than Mid and InStr. I even use .NET data types, such as Int32 instead of Integer, though I regularly get castigated for that. Especially when I write C# code and use Int32 instead of int, and Object with a capital "O". As I discovered, if you want to start a "discussion", tell a seasoned C# programmer that they are supposed to use the .NET classes instead of all those weird data type names.
I'm told that the compiler (C# or VB) simply translates the language-specific type name into the appropriate type automatically, and it makes sense for programmers to use the types defined in the coding language rather than specifying the .NET data types directly. Does it make a difference? I'm not clever enough to know for sure, but I can't see how it would affect performance because it's all IL code in the end. My take is that more and more programmers are having to (and are expected to) cope with more than one language. If you do contract work, and prefer to work in C#, do you turn down a job working on a project originally written in Visual Basic? If we are in for a global recession, as many suggest, can you afford to turn work away?
And what about those C# programmers who tell me they "can't understand Visual Basic". I can imagine that, if you've never used it, you would find it hard to write VB.NET code from scratch, though it surely can't take long to figure that you use "End" instead of a closing curly. OK, so the OO-features have quite different keywords (like "Friend" and "MustOverride"), but it's a lot easier than learning Portuguese (unless you're Portuguese, of course) or any other foreign language. Hey, almost all of it is .NET classes. Mind you, someone to crack you across the knuckles with stick whenever your fingers stray towards the semi-colon key would help. And I can't see how any C# programmer can say they can't read Visual Basic code. Again, the class modifiers and inheritance keywords are a bit different, but they aren't that hard to figure out.
OK, so it may sound like another rant against C# programmers, but I can assure you it definitely is not. After all, I'm half C# programmer, and I really do like the language. Weirdly, though, most of what I write (in terms of programming rather than documentation) is in VB.NET - I suppose it's force of habit and the comfort factor having come from classic ASP. Yet most of what I read (docs and code) is in C#. And, as they say in the movies, some of my best friends are C# programmers...
I suppose what I really want to know is: what's the test to see if you are "OO" rather than "OB". Is there a fixed number of interfaces and base classes you have to include in a project? Do you have to have at least 10% inherited properties and methods, and use polymorphism at least twice per 500 lines of code? If you forget to refactor one class, or use an array instead of a generic list, does that automatically disqualify you? Perhaps there is a minimum set of design patterns you have to implement per application. And what about the fact that I still use FileSystemObject in an old Web site I never got round to converting from classic ASP? Or is it that, secretly, you can only really be "OO" if you write in C#, Java, C++, and other "proper" languages...?