Random Disconnected Diatribes of a p&p Documentation Engineer
Suddenly, here at chez Derbyshire, it's 1996 again all over again. Instead of spending my days creating electronic guidance and online documentation in its wealth of different formats and styles, I'm back to writing real books. Ones that will be printed on paper and may even have unflattering photos of me on the back. And there'll be professional people doing the layout and creating the schematics. It's almost like I've got a real job again. I'll be able to do that "move all your books to the front of the shelf" thing in all the book stores I visit, and look imploringly at people at conferences hoping they'll ask me to sign their copy.
The reason is that we're producing a range (the actual number depends on how fast I can write) of books about the forthcoming version of Enterprise Library. I've been tasked with creating books that help people get to know EntLib and Unity, and get started using them in their architectural designs and application implementations. So the list of requirements includes making the books easy and enjoyable to read, simple enough to guide new users into understanding the basic features and their usage, deep enough to satisfy "average" developers who want to know more and learn best practices, and comprehensive enough to cover all of the major features that take over 1000 pages to describe in the online documentation.
They say that a job's not worth doing if it doesn't offer a challenge, so I guess this job is definitely on the "worth doing" list. And getting it all into books of about 250 pages will certainly be interesting as well as challenging. Maybe I can write very small, or use "txt speak". Need help using the Message Queuing feature of the Logging block? How about: "2 cre8 a msg q u use mmc & put name in cfg file thn cre8 logentry & snd. 2 c if it wrkd look in q". I can see my editor and proofreader having no end of fun with that approach.
But the hardest bit was actually deciding how (and whether) to provide sample code. Its likely there won't be room to print complete listings of all the code I use, which is probably an advantage in that readers can see and concentrate on the actual bits that are important. Of course, I need to build some examples to make sure what I'm writing actually does do what it's supposed to. So it seems sensible to offer the code to readers as well, like they do with most other programming books. But how should I present the code? As a pretty application with nice graphics and a delectable user interface? Maybe be all up to date by using WPF?
I remember when I first started writing books about "Active Server Pages" how we had no end of problems creating sample code that users could easily install and run. There was no SQL Server Express with its auto-attach databases mechanism, no built-in Web Server in Visual InterDev (this was the days before Visual Studio as we know it now), and you couldn't even assume that users had a permanent Internet connection (the vast majority were on a dial-up connection). So you had to create complicated sets of scripts and a setup routine, even for ASP samples, that registered the components you needed and populated the database, as well as providing a long list of prerequisites.
But things are much easier now. You can give people a zip file that they can just unzip and run. Even Windows Forms and WPF samples just work "out of the box". So, even though I haven't done much with WPF before, I thought I'd give it a try. I was doing OK with creating the form and adding some text and buttons, but then it came to adding a DataGrid. I thought maybe they'd forgotten to include it in the version of Visual Studio I'm using, but it seems that I wasn't prepared for the Wonderfully Perverse Features of WPF where you need to use Grids and ListViews and tons of stuff inside each one, then fight with Data Contexts and Binding Paths.
In ASP.NET I just grab a GridView and drop it onto the page. So should I do the samples as an ASP.NET application? That adds complexity with postbacks and maintaining state, and makes it hard to show some features such as asynchronous data access or cache scavenging. And it hides the real functionality that I want to show. Besides which, EntLib is really a library for helping you manage your crosscutting concerns, not a development environment for Web sites. How about Silverlight? Well, then I'm faced with a combination of the issues from WPF and ASP.NET. Maybe I should just take the easy way out and use Windows Forms. As a technology, I know it well and it provides all the features I need to create glorious user interfaces.
And then I remembered how long I've been writing code. Back in the early 80's, an attractive and intuitive user interface was one where you had a text menu on an 80 characters by 26 lines screen, and you could press any key you liked as long as it was one of those in the list. No need to mess about with sissy things like mice or trackballs, and no confusion about which things to click or where to wave your mouse pointer to see what things did. You knew where you were with applications in those days. And there's plenty of interest now in the old stuff such as text-based adventures and simple chunky graphic games like Asteroids and Space Invaders.
So why not follow the trend? Simple example applications that run in a Console window, have simple menus to select the specific sample you want to run, and use simple code to display progress and the results of the process. No need to run Visual Studio, the database will auto-attach to SQL Server Express, and readers can easily find the appropriate code in a single "Program" file if they want to read it all. In fact, I've seen this approach used by the guys from the data team here at Microsoft when they do presentations, and it really does seem to make it easier to see what's going on.
So that's where I'm going at the moment, at least until somebody else makes an alternative "executive decision" further down the line. What do you reckon? Do you want fancy interfaces for your code samples? Or are simple Console applications that focus on the "working parts" more useful and easier to understand? How about this for a flash-back to the past:
Or I suppose I could just publish the code as text files...
Oh well, back to work, holidays over for another year. At least I managed to morph from a sickly shade of pale to a faint shade of tan, and without catching airplane 'flu or any other weird tropical disease (at least not one that's shown up so far). In fact, it was one of the most hassle-free and relaxing holidays we've had. I even managed to forego the doubtful pleasure of email for a whole six days without caving in and searching for an Internet cafe.
Mind you, arriving home and deciding I should try to catch up with the mountain of emails that arrived while I was away was an interesting experience. It seems that my mailbox was upgraded to Exchange Server 2010 while I was away. While it doesn't affect using Outlook over HTTP, I'm battling vainly against the new version of Outlook Web Access. It seems to rummage around and collect every email it can find that vaguely corresponds to the one I'm trying to read, and then hides them all away in a tree view that you have to double-click to see the actual messages.
I suppose it's useful having all of the related messages collected together, even if it includes ones I sent, and even ones I've deleted (helpfully shown crossed out in the tree view). But I reckon it's going to take me a good while to get used to this approach. I spent the first ten minutes trying to figure out how to delete a collection of different emails - it seems like you can't just highlight them all and press delete any more.
And I can't find any options to go back to the old way either - in fact it took ages to find the option where I could turn off Out of Office Replies (which are now called "Tell people you're on vacation"). Maybe I'll just leave them turned on for good so I don't have to fight with OWA very often. Or just do what I ended up doing the evening when we got home and I was too tired to try and understand the new approach - use the cut-down "OWA Light" version instead. It's much like Hotmail (sorry, Windows Live Mail) - it just works like you'd expect.
Aha! (added later) I just found out you need click the little arrow next to "Arrange by" and uncheck "Conversation".
Anyway, getting back to last week's trip, I still haven't figured why it all went so smoothly compared to the usual hassle of traveling anywhere by plane. Yes, we did have to set off for the airport at 3:00 AM; but it's nearby, parking close to the terminal was easy, the check-in queue consisted of two people, there was time for a leisurely coffee, and then through security in less than ten minutes. Half an hour in departures chatting to people we know who happened to be on the same flight, then in the air fifteen minutes ahead (!) of schedule and arrival in Malta half an hour early.
With our taxi waiting at the airport, we were at the hotel within half an hour and ready to hit the beach! And it was just as easy coming home. Meanwhile, Malta is easy because they have real 250 volt electricity with UK-style sockets, and they drive on the proper side of the road (the left). Plus, all of the roads have meaningful road signs, even if every road you go down seems to take you back to the capital Valletta. Although the concept of giving way to others, even when they have priority, is more an option than a rule. I liked that all the roundabouts have a sign saying "Please obey the roundabout rules". I guess everyone does, in a roundabout way.
We did borrow a sat-nav with the rental car, and I'm really glad I didn't buy one like it. The helpful lady inside it had a habit of reading out the directions one turn early, then suddenly screaming "Turn left, turn left, turn left" just after you passed the junction (even when you should have turned right). I think the one word we heard most over the whole week was "Recalculating". Of course, it didn't help that the paper map of the island we were using to decide where to go contained English place names, while the sat-nav only had the Maltese equivalents. She even directed us up one street that started out about a foot wider that the car and then got even narrower, culminating in a right-angle turn. I got a lot of reversing practice during the week.
But if you are looking for somewhere relatively peaceful, pleasant, and full of history, Malta is worth a visit. Go in Spring or Autumn unless you like being burned alive, and - if you don't fancy driving - use the hop-on hop-off tour buses to see the sights. There are some lovely beaches, fabulous views, wonderful cathedrals and churches, a Roman villa, and an amazing walled city (Mdina) to see. It is a bit barren in places, and not the tidiest or best-maintained place I've ever been, but - hey - this is the Mediterranean. And everyone, everywhere, speaks good English. Here's some photos:
And, yes, I did find the house where I lived more than 40 years ago and even got to talk to the daughter of the guy who owned it back then! Meanwhile, I suspect we'll never be able to go on holiday again because it will never be this easy in future.
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.
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...
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...
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:
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...
I don't know how I manage it, but I seem to continually find myself trailing behind in this ever-changing world of digital technology. After the problems of a few weeks ago with a failed Media Center box (which, it seems, can't be fixed) I've finally got the new replacement machine up and running. We've been magically transported from the gray and disappointing confines of Media Center 2005 into the vibrant and exciting new world of Vista Media Center - just a month before Windows 7 is released. I suppose our only hope of actually catching up with O/S releases will be if next door's toddler happens to shove a slice of buttered toast into the DVD drive so we need to buy another new one.
But I must say, the new box is rather nice. It's basically a Shuttle system specially configured by an outfit called I.US to run as a fully capable Media Center. There's a twin digital TV tuner and some software to help Media Center go to sleep and wake up again, a Blu-Ray drive (though Media Center can't show Blu-Ray disks so you have to use the alternative player they provide for them), and a nice wireless keyboard. It came with a suitcase full of extra cables and stuff, and a natty USB wireless network dongle (though we are mainly hard-wired in our house). It looks pretty and, nicest of all, is extremely quiet. Yet it runs Vista and Media Center well, with few indications of performance issues.
And one bonus is that I finally figured out (with some help from other people's blog posts) how to get rid of the annoying auto-login problem with my wife's Vista laptop. Since I set it up, it's been refusing to do auto-login with a "wrong password" error, despite me fiddling endlessly with the limited settings in the Vista account management dialogs. But I had to resolve the problem so I could get an account to auto-login on new Media Center box. The I.US people do a full setup of the O/S, including registering it and running a series of tests such as copying and burning a DVD, tuning the TV cards, and configuring stuff like updates, UAC, and Media Center options.
They create a single admin account with no password, so the system automatically logs on. However, if you want to interact with other machines on a Server 2008 domain (even though you can't actually join the domain), you are stuffed because domain policy prevents the use of blank passwords. Rather than change this behavior, or risk breaking something by changing the default account password, I created a second account on the Media Center box with the same credentials as a user account on the domain so that I can do backups and access the media storage folders on the network that have "Everyone" permission. As I discovered, if you create a mapped drive using a different set of credentials from the logged on user, it conveniently forgets to use them when it tries to map the drive at logon. Most annoying.
I guess it's another indication of how Vista hides stuff and tries to make things too easy in that you have to go through a convoluted process to get an account to auto-logon when there is more than one, or when it has a password. It involves a command line option to open a hidden wizard, and some unintuitive setting and clearing of checkboxes and selecting stuff in a grayed out list box. For details, see Automatic logon at startup in vista. It seems that this process prepares the account for auto-logon by updating the same section of Windows registry as you used in XP to make this work, but it stores the password somewhere safe rather than as text in the registry. Interestingly, after configuring it, you can't just do a "Switch User" and log on with that account. You have to reboot, but then it all seems to just work.
One hang-up was the fact that the home-grown custom photo screensaver we've used in Media Center 2005 doesn't work in Vista. However, there is a nice photo screensaver in Vista with lots of clever display options. Except on the new box, the screensaver settings dialog said that my graphics card "does not support themes". So I could only use the nasty basic version. A few forum posts revealed that the video card needs to support "Vertex Shader 2.0", but that didn't bear any resemblance to the meaningless gobbledygook options in the Nvidia control panel.
However, it turns out that Vista also requires a performance index of higher than three, yet it doesn't actually do a check - it relies on the results of a previous calibration by the "Is My Computer Any Good" wizard in Control Panel. When I opened that, it revealed that my whizz-bang super-fast (and rather expensive) new box scored just 1.0. However, after running it again I got 4.8 - maybe I even qualify for a place in the "my computer's faster than yours" forums now. And, back in the screensaver properties dialog, I've got a choice of any theme I like! Didn't anyone think that this would happen when they were designing it? I suppose it does make sense in some way, but why not provide a link to run the wizard, or at least a note to explain the consequences of this behavior. The help file doesn't suggest running the wizard until you click through three pages. It mainly thinks I should just go out and buy a better video card.
Strangely enough, this "didn't anybody think this was going to happen" scenario also kind of coincided with a newspaper report I was reading this week. It seems that, here in Britain, we are "the swine flu capital of Europe" with over 10,000 new cases occurring every day. The men who supposedly run the country took immediate steps to limit our suffering by setting up a "swine line" call center with 3,000 staff. Of course, none are doctors so they work from a script to determine if the caller has swine flu. Helpfully, they published the symptoms in the script in all the national newspapers and in leaflets sent to every household. If you think you've got it, you call them, answer the questions, and they give you a code number that your "flu buddy" can to take to one of the special "swine flu centers" to get your dose of Tamiflu and a no-questions-asked sick note for a week off work.
Turns out, as you'd probably expect, that most of the people using it are just looking for a free week off work. In fact, the peaks in the graph of "new infections" neatly coincided with the weeks when the weather was nice. I hear that seaside resorts and amusement parks are all reporting record takings this season, so probably there's only seven people in England that actually have flu. However, according to "a Government spokesperson", the "skivers" will have "a real problem" when the flu does its usual trick of reappearing in the autumn, and they really do catch it. Though I suspect it will be their co-workers and the people they share the bus and train with that will actually have the real problem...
But at least we'll be able to watch TV now when we're stuck home with our Tamiflu tablets, hot lemon drinks, and (for medicinal reasons obviously) a few whisky chasers.
In between the usual spates of frantic two-fingered typing of exciting new guidance this week, I've been attempting to expand my brain to the size of a small asteroid (with appropriate apologies to Douglas Adams fans, the size of a planet seems a rather optimistic aim). All this comes about because an increasing amount of stuff in the project I'm working on at the moment, the upcoming version of Enterprise Library, depends on new whizz-bang features of the .NET languages such as lambda expressions, nullable types, anonymous delegates, and implicit typing. As an upgraded VBScripter, much of this might as well have been written in Klingon for all the sense I could make of it.
It means I've had to do a crash course in advanced C# so that I don't look too much of an idiot at product meetings and demos by asking stupid questions such as "did you miss the word 'delegate' out there?" or "shouldn't the 'select' bit come first?". So I've been reading (and re-reading) a book by fellow Englishman Jon Skeet called "C# In Depth" (ISBN 1933988363), and I can definitely recommend it. It skips the usual "What .NET is", "How to do foreach loops", and the history of the Internet; and dives straight into the exciting new stuff in C# 2.0 and C# 3.0. It's well written and understandable to mere humans, yet delves deep into the topics and really makes sense of them. The only criticism I have is the overuse in almost every chapter of the excruciatingly awful term "syntactic sugar" when referring to the new language features.
And I've even had to order an equivalent VB.NET book as well so I can figure out how do code sample translations for the docs, and write my own demo code in both languages without just cheating and using Telerik's useful Code Converter site. It will be interesting to see if the combination of explanations from two different authors, in two different programming languages, makes the topics clearer or just more incomprehensible. Maybe after I've read them both a few times, my brain will be approaching small moon size. Perhaps I can even persuade people that my increasing bald patch is due to "syntactic squeeze" inside my head forcing out the few remaining gray hairs.
But what really prompted this week's doubtful diatribe was a throw-away comment in Jon's book. He says (though I'm not allowed to quote the actual words due to copyright restrictions) that developers previously had to rely on manually written documentation, whereas the syntax of the recent versions of languages such as C# 2.0 and 3.0, combined with the increasing capabilities of IDEs such as Visual Studio, means that this is no longer required. He suggests that documentation is often incomplete or inaccurate, and that developers rarely read it anyway.
This is kind of worrying, especially as a large part of my job is to create documentation for code projects, rather than just architectural guidance. And it seems that the bits developers do rely on most are the API reference sections that simply list and describe the classes and their members; and is built by an automated process from the generated assemblies, XML, and PDB files. OK, so this does depend to some extent on developers putting meaningful summary sections in their code for it to make much sense, but I can't see Microsoft paying me full time just to click the "Go" button in Sandcastle once a month. Do I need to start looking for a new job?
Yet, I'm not convinced that the huge amount of effort we put into producing documentation for p&p projects such as Enterprise Library is a waste of time. Yes, given a requirement to write a function to calculate some esoteric mathematical result, or interact with a Web Service, or even a whole application to do some kind of data processing, you may only need to know about the syntax and usage of elements of the language. Maybe that's what Jon was getting at. But when it comes to understanding a new technology, code library, or development framework, surely developers need some additional assistance in the form of written (or other format) guidance.
Most of the effort we put into documentation for things like Enterprise Library involves an overview of the feature so you can grasp what it does, when you should use it, and see an outline of how it works so you can understand it. Then there's information that's hard to get from looking at the code or using IntelliSense; such as configuration settings and their effects, recommendations on choosing appropriate methods and overloads, explanation of the return values and the ways you can use them, and more. I can't see how the brief descriptions in an API reference can provide this kind of assistance.
Or could it be that I'm just not a capable enough programmer to be able to do it without somebody holding my hand? Maybe I just need to get to know more people with planet-sized brains...