Random Disconnected Diatribes of a p&p Documentation Engineer
I previously thought that the reason you used to see miles of cassette taped entwined in the bushes at the side of motorways was because the driver discovered that his or her Mother had accidently put a "James Last Plays Christmas Carols" tape back in the driver's Black Sabbath or Pink Floyd cassette box. Needless to say, that kind of disaster when hurtling along the M1 could obviously engender a malicious and wholly illegal "chuck it out of the window" process. But it seems I was mistaken.
According to the Surrey Advertiser newspaper (a local rag available in the southern part of England) nefarious devil worshippers are intentionally recording dark and dangerous spells on cassette tape and then diligently encircling sections of the Queen's Highway with it to initiate a huge crop of accidents and other unfortunate occurrences. In particular, at junction 9 of the M25 they have prompted a noticeable increase in the number of motoring accidents and suicides from people jumping off the footbridge. A group of believers from the Pioneer Engage Church even organized regular vigils and prayer meetings to "cleanse the benighted interchange".
Now I'm fairly open to wild new theories and improbable suggestions. I mean, I even accept that information technology can create a paperless office. And that sat-navs actually do use satellites circling way above the earth rather than reading the location from barcodes in the white lines on the road. But I'm finding it hard to believe that the magnetic properties of cassette tape are sufficient to overcome the Earth's residual magnetism at a level sufficient to affect human behavior. Especially as we're repeatedly told that holding a powerful microwave transmitter right next to your ear is not the least bit dangerous.
As an aside, I just watched a program by Stephen Hawking about how time works that said the clocks in the GPS satellites need to be manually adjusted as they gain a billionth of a second every day. This is, it seems, because the effects of gravity make time run slower close to the Earth than at the satellites' altitude. Supposedly, if they didn't do it, your sat-nav would be out by six miles every day. Maybe the reason I still get lost some days is because the guy who winds the knobs took a day off sick.
So, anyway, the Surrey Advertiser soon received several disbelieving responses to its article, including one from a reader who (perhaps through intimate knowledge of the practice) pointed out that most evil spirits these days use MP3 players because they are far smaller and more convenient to carry when crossing into the dark realm and back again. More likely is that, when our intrepid band of believers analyzed the contents of the tape, they accidently played it backwards and by sheer luck hit upon the bit in Led Zeppelin's Stairway to Heaven that supposedly includes satanic phrases recorded in reverse.
But maybe it's the reason that people hang old CDs on strings to scare birds away from their vegetable plots. It probably works best with heavy rock music ones. I suppose I could subject the theory to scientific test by burying a hard drive containing all the satanic album tracks I've collected over the last forty or so years under the hedge at the front of our garden, and counting the number of people who fall over as they pass by...
Well I'd have to say I haven't had so much fun for ages. Playing with familiar stuff (and some less familiar stuff) has revived my joy of writing complicated algorithms and creating useful utilities. It's almost like being back in the old days of creating COM components for classic ASP web sites to do the things that VBScript couldn't do. I even got to write some more VBScript - and, yes, it was a politically correct circumstance 'cos I was executing it through Windows Script Host.
Over the past few months I've been revisiting some old utilities I created - in some cases years ago - that would actually be useful again. For example, I now have a dual failover Internet connection (ADSL and cable) so if the ADSL fails, which it does fairly regularly, I don't get to know that the local village and parish web sites I host are offline until the condescending emails start to arrive.
So I revived an old web site checking utility and updated it to VS 2008. By running it on an internal machine, and going out on the cable and back on ADSL, it gives me a proverbial nudge when the ADSL line is down. It just needed some fettling to resolve a few poor code practices applied at the time, a few extensions to make it do additional things, and a UI makeover to make it seem less amateur (though with my design skills, I probably only managed to make it contemporary with the late 20th century).
However, prompted by this flush of success, I expanded the log file monitor that I threw together some time ago to try and fend off the DNS amplification attacks I was suffering at the time. Now it monitors DNS, WWW, and SMTP logs with a broad range of search options. It can also send email notifications and execute scripts or programs. I use this feature to execute the aforementioned VBScript script to automatically create and manage IP address blocking rules in Windows Firewall (WFWAS).
Finally, I decided to tackle the problem of synchronizing specific sets of files between two machines. Yes, I know there are several ways you can do it in the O/S and with other utilities, but I wanted to be able to view and control the process in several specific ways. It comes about because I have a computer that contains the set of folders and files synchronized with Team Foundation Server (TFS), but I tend to work on other computers with individual subsets of these files. It's also made more complex by the fact that the files are read-only in TFS when not checked out, and the file date controls whether files are updated in TFS when you synchronize.
The idea was to be able to see the two sets of files (local and TFS) with information about the date/time, archive status, relative path, read-only setting, and easily see which were newer than the equivalent in the other location. I also wanted to be able to copy, synchronize, merge, delete, and set the last-modified date with one click. The result saves me loads of time and effort, and probably helps to avoid errors when managing the files. OK, so I probably won't be subjecting the source to a proper code review, but there are only a few bits left in there that I'm embarrassed about.
If you want a copy of any of these, you can download them here. I've even included the VS2008 source code so you can see what they are doing - as long as you promise not to show it to anyone (or laugh)...
But I suppose the real reason for all this rambling scribble is that, during the process, I realized just how much fun basic task programming really is. It's like discovering the old home computers all over again, but much easier this time round. It really is amazing how .NET and the powerful framework classes save a ton of effort. I'm by no means a virtuoso programmer compared to most of my learned colleagues, but having things like complex conditional statements, capabilities such as generic lists, and features such as simple file and folder handling functions available really makes it easy to concentrate on the algorithmic logic rather than worrying about file modes and array indexes.
And, because my history in languages pretty much follows the evolution of Pascal, Delphi, classic ASP, VB for Applications, and Visual Basic as far back as version 1.0, I'm still most comfortable using VB.NET. While almost everything I do in my p&p day-to-day work is C#, I still find VB easier to read and write, and I love the way it does all the magic indenting and formatting for me. And, of course, it runs just as fast as C# (as long as you write good code) so I now only feel like a one-and-a-halfth-class citizen in our wonderful world of technology, rather than the second-class citizen I was before the advent of .NET.
What continues to amaze me, however, is how - after I agonize about every minor instruction I need to add to make the algorithms work, and every extra conditional statement they require to cope with the increasing complexity as I decide to add yet another configuration option or code tweak - they still seem to execute in the blink of an eye. I mean, you'd expect that parsing a web log file when the decision tree takes up a whole page in Visio would take a week to run. Or than reading two folder trees to build the lists of files and doing all kinds of comparisons before displaying them in two DataGridView controls would leave you time to make coffee, eat the remains of that cold pizza, and finish the crossword as well.
But, with the memory and processing speed available on modern computers, everything just seems to fly. I'm expecting it to splutter and crawl like a caterpillar in custard, but instead it dances like a cat on a hot tin roof. Even my VBScript script that updates Windows Firewall runs so fast that the screen update can't keep up with it. I ran it three times wondering why it wasn't working, and only discovered it was when I looked at the log file...
Maybe I'm picking up some good programming habits from the plethora of clever code I encounter every day in my proper job. Perhaps the constant exposure to design patterns, extensible code techniques, and the latest features of the framework are gradually permeating my aging brain. Or is it just that a quad-core Xeon box with 8 GB of memory can eat any code I throw at it without even blinking? Does replacing my complex sets of arrays with generic lists of custom classes, and my Ands with AndAlsos in the appropriate places, really have any discernable effect on execution time? Or am I just pandering to the typical programmers' paranoia of wasting any of those valuable execution cycles?
But there is always that wonderful warm glow inside when, after pondering over recalcitrant algorithmic constructs for ages, it all works as though it was written by somebody who actually knows what they're doing. And, anyway, I have to stop writing now. I need to think up some more exciting new and totally unnecessary features to add...
Which is the best way to prevent intrusion attacks on your server from the network? What is the largest size of application XAP file you can deploy to a Windows Phone 7 device? When should you cache the data used by your application in memory? How many magicians does it take to change a rabbit? Obviously the correct answers are "Unplug the network cable", "400 MB", "Always", and "None, it's just a trick".
Or are they technically "correct"? Can you equate "best" with "basically, the server's not working any more"? Certainly it's the most positive and reliable way to protect your server, but it's somewhat lacking in practicality in terms of a non-broken network. And what about Windows Phone 7 users who rely solely on their phone supplier for connectivity? The maximum size of a XAP file you can download without using Wi-Fi or a USB cable is 20 MB. And, of course, caching a 3 GB collection of data transfer objects when your computer has only 2 GB of memory may not provide better performance...
All this comes about because we decided to include the now highly fashionable "Check Your Understanding" section in all of the chapters of our new Windows Phone 7 Developer Guide. I can't say I'm a huge fan of these sections as they add to the effort of creating the guidance - though I do agree they are useful. I used the ones in our recent Parallel Programming with Microsoft .NET guide to figure out if I actually did understand any of the topics in each chapter. Mostly I patently didn't, but that's a different issue for which I can't blame the authors.
So, anyway, having agreed to include them in our latest tome I had to figure out the appropriate style and content. I started by watching some TV programs that supplement their income by offering cash prizes for answering a simple question. Based on this, we'll be including a knowledge check such as:
Which of the following is a well-known computer operating system?
OK, maybe more research is required. So I check out the program for people who want to be millionaires. How about:
What does the computing abbreviation "AMLCD" stand for?
So, you see, it's not as easy as it might seem. And how many questions should there be? How difficult should I make the questions? Will they actually help people to understand the content of the chapters? Can I include one or two stupid answers to liven it up? Will all this asking questions about questions finally result in a stack overflow error?
In the end we decided on six questions per chapter, multiple choice from four possible answers, and medium-level in terms of difficulty or obscurity. Such as:
Which of the following programming techniques are permitted in a Windows Phone 7 application?
The next step is to provide the answers. Annoyingly, I haven't found a way to display them upside down at the foot of page 97 using HTML - but that's the production department's problem, not mine. All I need to do is supply the text for the answer. And it's obvious that the answer to the previous question is "None of the above". Easy! And I've reinforced the reader's understanding by checking that they will remember these limitations when they start designing their Windows Phone 7 applications.
But, unfortunately, the dreaded cyclic dependency factor now comes into play. One of the major things I learned from working on the Microsoft Application Architecture Guide guide a year or so ago was that, for any question you ask an architect, the answer will always be "it depends". And the same applies, it seems, to most other computing-related stuff.
Looking back at the question above, you would have to agree that "a" is not permitted. The requirements for Windows Marketplace certification clearly state that your application must work on any device that meets the Windows Phone 7 specification, and extended memory is an optional feature of the phone. Except, elsewhere, it says that the maximum memory usage for a WP7 application is 90 MB unless the device has more than 256 MB of memory installed. But then it says that the application must run anyway, and only take advantage of extended memory when it is available. So, in a round-about way, it seems that "a" actually is not permitted.
What about "b" and "c"? These are both definitely not permitted, so we're OK there. Except that I was told that OEMs developing Windows Phone 7 devices can use C++ and native (so technically unsafe) code. So if you were feeling picky, you could dispute that part of the answer we provide. But, in general, we're still OK I reckon.
And so, finally, is "d" permitted or not? Well, it seems the issue is that the Marketplace submission process unpacks the XAP file you provide, scans the code to determine the security permissions it requires (for things like using the microphone, camera, location service, etc.), and then recreates the manifest file in the XAP so that it lists only those actually used by the application. This means that Marketplace can list the phone features the application uses with confidence that only these can be used in the code.
But the Marketplace code scan does not find types that are discovered and instantiated using reflection. Therefore, if you use this approach to locate and instantiate a type that requires security permission, and the application manifest does not include that permission, your application will fail with a security permission error. However, if you have already referenced the type using the normal approach the manifest will contain the required permission, and so the app will run. Technically, the programming technique described in "d" is not "not permitted", but rather it's "discouraged" because it is likely to cause the application to fail in most cases.
So, even though I wrote the question, I actually got the answer wrong. I told you this was harder than it looked...
I can't help wondering what people will actually make the effort to go and see in a hundred years time. What are we creating now in terms of engineering marvels or wondrous architecture that our grandkids' grandkids will pay money to visit? Compared to the places we went on out recent tour of England, what will be worth visiting - or even still be there - in the twenty-second century?
Yes, I know stuff like the Pyramids (and Stonehenge here in England) have been around for a lot longer than 100 years, as have most cathedrals and the natural wonders such as the Grand Canyon and (on a somewhat smaller scale) Cheddar Gorge. It's probably safe to assume that people will still be making the trip to visit these and other similar sights a hundred years from now.
But there is so much relatively recent history that attracts millions of visitors each year, but seems to capture only a brief instant in time. In particular, here in England, the incredible feats of the Victorians and Edwardians who changed our landscape and created the forerunners to many of today's architectural and engineering achievements. You only have to look at the railways, the canals, bridges of all kinds, the iron steamships, the factories and mills, the huge country houses and palaces, and the wonderfully landscaped estates and gardens.
So what will we leave as the epitaph for our own brief instance of time? What have we created in the last hundred years that deserves to be part of our heritage? Will people in 2110 walk around a cruise ship marveling at the five swimming pools and luxurious dining facilities? Will they stroll along abandoned motorways/freeways reminiscing about the cars and trucks that used to thunder up and down them all those years ago? Will they stand in abandoned departure lounges wistfully remembering the gaily colored aircraft that used to ferry people to foreign destinations?
And what about architecture? Will any of our fabulous suspension bridges survive for 100 years? Will our modern houses and commercial buildings be worth visiting in years to come? Have we really built anything that will astound people in the future with its daring use of materials and leading edge construction methods? Or, alternatively, seem as quaint and picturesque as an "Olde Worlde" country village?
And what about monuments to our technologies? Maybe people will peer into the derelict clean rooms of our semi-conductor factories and be amazed at the massive size of our silicon chips. Or stand in the tunnels of the CERN accelerator in Switzerland and hear stories about the search for particles that their kids now routinely create in school physics lessons. Perhaps they'll visit the now deserted motor car plants and be appalled at the working conditions that prevailed. They might even organize tours of our neglected hospitals and listen in horror as the guide explains the medical procedures that were common in the twenty-first century.
Yet, somehow, I don't see it. I wonder if there was a special period in time when things were changing so fast and with such incredible impact that we cannot even come close to now. OK, so we've changed the world dramatically in our own time with electronics and networks, and our knowledge-based economies. Maybe all we'll have for people of the future to visit is massive datacenters, and lots of pictures and videos on the Internet...
OK, I might as well admit it - I'm a mobile technology dinosaur. My mobile phone is obviously of no use at all these days because the only thing you can do with it is make and receive phone calls. As I discovered a couple of weeks ago while on a brief touring holiday around England by car, I'm no longer fit to use facilities such as motels and travel lodges. I'm officially a second-rate citizen in our high technology mobile device-enabled world.
Why? Well, as an ex Boy Scout, I thought it would be a good idea before we set off on our travels to print off a list of phone numbers for the reservation centres of the major motel and travel lodge chains so we could just phone and book a room at the nearest one as we roamed unpredictably across the country taking in museums, preserved railways, public gardens, beautiful scenery, and ducks (at the Slimbridge Wildfowl Trust if you were wondering about that last one).
So, would you believe that almost none of the usual motels or travel lodges publish a central reservations number on their web site any longer? Of course, there are plenty of interactive online maps showing the locations, with the pop-up details I need for each one. But if you follow the link to book by phone, it starts off by telling you to open a web browser and access the reservations page. Yeah, that will work when I've only got ten buttons on my phone and a less-than-one-inch-square screen. Of course, I could just print off a list of all that company's locations, but the list doesn't include phone numbers or addresses. It's just links to other pages on the Web site.
I suspected that the world of mobile phone technology was leaving me behind a while ago when I tried to buy a replacement clamshell-style phone for my wife because her very nice Motorola RAZR V8 had decided to fall apart (obviously an event that was in no way connected to dropping it onto a tiled floor). But there is nothing like them available. Everything is big screen, full color, web-enabled, and too big to easily carry in your pocket.
So is there a future where a mobile phone will be just a phone? Or is it that mobile phones will no longer need to actually be a phone at all. We'll just use Voice over IP (VoIP) for the increasingly rare occasions when we actually want to communicate using speech; and the web for everything else. I suppose they'll have to think up a new name for such devices. Maybe we can call them IPads.
Of course, I could just buy a mobile dongle for my laptop and take the whole caboodle everywhere with me instead. I just looked on the Web site of my current phone supplier to see if I could buy a broadband dongle for when we go to Cyprus. But when I entered my postcode it said they "didn't recommend use in my location", so I can't use it at home. And, further down the page, it says that they don't support use outside of the UK at all, so it's no use for my upcoming trip to Cyprus either. It sounds like the only time I could use it is if I drove to my nearest town here in England and sat in a car park. One that is in a "recommended location", obviously.
Or maybe I should just stay at home until December, and buy a Windows Phone 7 when they finally appear...
I'm not quite sure why my blog seems to have got stuck in some science fiction oriented hysteresis loop at the moment, but I might as well take advantage of it after reading an article last week about creating tailor-made Universes. And this, supposedly, actually isn't science fiction. As the renowned Dr. John Gribben explains in his book "In Search of the Multiverse", it's perfectly possible - in fact quite likely - that our own Universe is actually just a member of a collection (or generic List maybe) of Universe instances in a Multiverse.
It seems that the only way physicists have discovered for making a Universe is to start with a black hole and have it explode and release into the ether all of the mass it contains - rather like the recent global finance black hole where the banks exploded and all the money evaporated into the ether. And, expounding on the theme, if we are part of a Multiverse it's supposedly almost inevitable that somebody in another Universe originally created our black hole (the mass one, not the money one).
And by carefully modifying the initial settings (such as the force of gravity) and other content, it seems like they could influence the development and future evolution of the new Universe to some extent. Rather like the way we carefully tailor the target and content of our guidance here at p&p before launching it into the wild world of the Web. Of course, unlike our guidance, once it sets sail the manufacturer of the new Universe has no control over it. So the state that the world is in now is entirely our own fault.
Making a black hole is, according to the article, not that difficult. They reckon that the Large Hadron Collider (LHC) at CERN in Switzerland could make very small ones - a fact that has alarmed some people to the extent of taking legal action to prevent them using it at all. Making very large ones is, of course, likely to be more problematic (and dangerous). To give some idea of the difficulty, the article explains that you would have to compress the earth into a ball about half an inch (one centimeter) in diameter. Or, to provide a p&p-related allegory, compress the entire documentation set for Enterprise Library 5 into a 4-bit integer value.
So perhaps Terry Pratchett's story about how the Wizards at the Unseen University inadvertently created our Universe and "Roundworld" (the Earth) when their experimental thaum-splitting reactor went out of control is not just fiction. Or maybe Gregory Benford's novel "Cosm" about a disobedient particle accelerator creating a baseball sized Universe is more prophesy than just an entertaining read. Of course here at p&p, where we're always at the leading edge, we'll need to provide some guidance on the process. Most likely including a table of members for the new Universe:
Constructor: Creates a new instance of the Universe class and sets the name for the new instance. Use the var keyword when defining the return type as the actual type returned is likely to be previously unknown.Syntax: var myUniverse = new Universe("Sample Universe")
var myUniverse = new Universe("Sample Universe")
Property: GravityRatioDescription: Gets or sets the relative gravity ratio for an instance of the Universe class. The value must be a member of the UniverseGravityRatio enumeration. Syntax: myUniverse.GravityRatio = UniverseGravityRatio.WowThatsHeavy
myUniverse.GravityRatio = UniverseGravityRatio.WowThatsHeavy
Property: SpeedOfLightDescription: Gets or sets the speed of light in metres per second for an instance of the Universe class. Values less than 5 may impact the operation of forthcoming technologies within the new Universe, such as cable TV and lighthouses.Syntax: myUniverse.SpeedOfLight = 250000000
myUniverse.SpeedOfLight = 250000000
Property: PaperWorkRatioDescription: Gets or sets the ratio of detectable matter in the new Universe instance. All Universe instances appear to contain less matter than is actually required according to the laws of physics. The remainder is the paperwork. Typically this is around 75% of the total.Syntax: myUniverse.PaperWorkRatio = 0.7
myUniverse.PaperWorkRatio = 0.7
Property: IsPlancksConstantConstantDescription: Gets or sets a Boolean value that determines if Plancks constant will be variable or constant for an instance of the Universe class. Setting this value to false may have indeterminate effects such as raising the level of uncertainty for the results of measuring physical items within the Universe, and increasing the number of cats. It may also affect the quantizational stability of electrical charge, which is typically appropriate only if your company manufactures Uninterruptible Power Supplies.Syntax: myUniverse.IsPlancksConstantConstant = false
myUniverse.IsPlancksConstantConstant = false
Method: DoBigBang()Description: Starts the instance of the Universe class running. Note that the Universe instance will run on a background thread, which means that you will not be able to interact directly with the user interface.Syntax: myUniverse.DoBigBang()
Method: Clone()Description: Creates a backup copy of the Universe instance. This allows you to restore it following a configuration error or failure during operation. Backup copies should be protected with a strong password and stored in a secure location.Syntax: var myBackupCopy = myUniverse.Clone()
var myBackupCopy = myUniverse.Clone()
Mind you, what's somewhat worrying is if Douglas Adams actually knew all about this from the start, and summarized it in one of his more well-known comments: "There is a theory which states that if ever anyone discovers what the universe is for and why it is here, it will instantly disappear and be replaced by something even more bizarre and inexplicable. There is another which states that this has already happened."
Is it still a holiday when you never seem to stop travelling, you can't quite figure out what day it is, you're not really sure where you are, and you can't remember where you are supposed to be tomorrow? It sounds a bit like a mystery tour, which is somewhat worrying as I was actually doing the driving. And doing the planning (or, to be more accurate, the lack of planning). Still, we had a great time. And, yes, I just sneaked a few days away from my daily documentation duties to grab a brief respite from all things Windows Phone-oriented.
As we are due to fly off to Cyprus for a wedding (not ours) in a few weeks time, we decided to skip the airport hell and, instead, see some of the sights in our own country. OK, so we did kind of have a kind of plan, which included starting at the Eden Project in Cornwall and working our way home via a disparate selection of tourist-oriented delights and wonders. So I'd already booked one night in a hotel in St. Austell and bought tickets for the Eden Project online before we departed. And starting bright and not very early on Monday, we set off on the long and arduous 300 mile drive to Cornwall.
Except it wasn't either long or arduous. Even though we'd planned it for after the kids went back to school, I was amazed to find the roads nearly empty; so that, within a couple of hours, we were closing in on Gloucester on the M5 and decided to pull in at a service area for a coffee and a bun. So how come the place was packed so full we couldn't find a parking space? Where did everyone come from, and why were they here? Maybe that's why the roads were so quiet - everyone stopped at this particular service area and liked it so much they decided to stay for the week.
So, as we weren't due in Cornwall until late that evening, we detoured instead to visit a couple of my old haunts from when I lived in Gloucester a great many years ago. Cheddar Gorge (amazing), Wookey Hole (even more amazing), and Wells Cathedral (incredible). All well worth a visit, And, wow, three touristy things done and still a week left. Maybe we can go in for some kind of a record.
Next day, the Eden Project. Yes I'm a gardener, but only in the sense that someone who can boil an egg is a chef. But everyone says it is worth a visit, and they aren't wrong. It's also great exercise because they built it at the bottom of a very large hole, so you get a lot of practice at walking up and down hills. And while the open-air gardens are very nice, the real attractions are the bio-domes; of which the tropical rainforest one is fabulous. As well as sweating like a pig and getting bitten by ants, you really get the feeling you are in somewhere like the Amazon - except for the little signs on the trees that tell you what they are (I haven't been to the Amazon, but I assume their trees aren't labeled).
The next day we started the journey home via the remaining tourist attractions we'd planned to see. Except that my wife found the Tamar Otter Sanctuary in Launceston on the sat-nav so we only got thirty miles the first day. She loves otters, and there is the bonus of seeing deer, ducks, Scottish wild cat (there was only one), owls, and wallabies. The last of these was somewhat of a surprise - it seems an unusual mixture when it comes to selecting an animal theme, and I'm sure wallabies aren't native to Cornwall so they didn't just wander in by accident. But it's certainly a very nice laid-back and wonderfully relaxing place to visit.
My vague journey semi-plan indicated that the next stop was Slimbridge Wildfowl Trust, but somehow my wife persuaded me that we should drop in at Dawlish Warren on the way past - it was only a fifty mile detour. It seems that her friend's Mother goes there for a fortnight every year, so it had to be worth a visit. Hmmm, I guess if you enjoy a large field, small beach, and very limited facilities including a funfair and one shop it's great. Though I have to admit that it actually is a very quaint and attractive area. And there was even a railway there, so at least I was able to do a bit of train-spotting. And it would have been even better if any trains had actually decided to come through during our brief visit.
At last we got to the Slimbridge Wildfowl Trust. I really enjoyed this place, though I've probably now seen enough ducks and geese to keep me happy for a couple of years. And the way they follow you around is rather eerie. Every time you turn round, there's two following you and they won't go away until you take a photo of them. Two Nenes (Hawaiian Geese) followed us all day, despite me taking their photo several times. The reception desk people also give you a book with pictures of over a hundred ducks and geese so you can identify them. Shame then that the one duck that came and sat on our table while we were breaking for coffee wasn't in the book. Though it does say in the small print that it only shows the males in their summer plumage, so maybe this was a female or - as it was cold and raining - it'd already donned its winter attire.
After Slimbridge, the next day was Ironbridge Gorge Museum near Telford in Shropshire. Or, to be strictly accurate, ten museums. And all on the same single entrance and car park ticket. OK, so we wearied after about six and didn't do them all, though the tickets are valid for a year so no doubt we'll be back there again. But the ones we did visit are superb, especially the Blists Hill Victorian Town. A really amazing place, especially if you have an interest (as I do) in feats of Victorian engineering. There's canals, an inclined plane boat lift, iron casting, brick and tile making, Victorian shops and businesses, and more. I even consulted a Victorian doctor in his themed surgery about the pains in my weary legs from all that walking, but all he did was moan about the youth of today (circa 1890) and then charged me sixpence.
Ironbridge also offers you a chance to walk along a tunnel where bitumen drips from the walls (and you get to bang your head a great deal), see people making Coalport pottery, learn about the archaeology and history of the gorge, and - of course - see the actual iron bridge (the first of its kind, erected in 1779). Plan to be there for two days if you want to see it all.
Finally, my own choice, the Severn Valley Railway. It's nearly 25 years since I last went there, and it's changed quite a bit since. There's an extra few miles of track, a brand new (but built to an original old design using old materials) station, a new engine house museum, and loads more rolling stock and locomotives. Unfortunately, there's also more new restrictions on where you can go. Though I guess the active loco sheds and works are a little too dangerous in today's Elf and Safety society to be open outside of planned tours. But, if you have even the slightest passion for railways, you just have to pay a visit. It's by far the best of the many preserved railways in this country.
So that's it. Best part of a week travelling, sight-seeing, reminiscing, and walking up and down hills. But what a great way to get away from it all...
I'm sure my wife won't mind me publicizing the fact, but she is rubbish at packing stuff. When loading a car, instead of starting with the biggest items she starts with the nearest ones and then finds that there isn't room for the big items - and there are no small or medium sized bits left to fill the gaps either. Or, when we're going on holiday, waits until the suitcase is full and then decides to take four pairs of high-heeled shoes.
So what has this to do with guidance, p&p, and documentation (or, in fact, with anything)? Well, packing a book with content is very much like packing a car or a suitcase. There is only a predetermined amount of room for the necessary verbiage and schematics, and you have to put stuff into it in the correct order or it just looks like an embarrassing jumble when you get stopped at customs. The trouble is, writing a book by putting the big things in first and then filling the gaps round the edges doesn't seem like it will work. Especially if you don't actually know what the big things are when you start.
I don't know if it’s a universal truism, but I reckon that to get the makeup of a book right you must be able to see the complete finished work in your head before you start to write anything. It's all about figuring what the Table of Contents will look like before you commit finger to keyboard. OK, so maybe this approach doesn't work when you are writing fiction, though having a detective novel where you only decide who was the murderer when you start to write the last chapter seems unlikely. Discovering that Colonel Prune did it in the kitchen with a gas pipe when, by the end of chapter 2 you were convinced it was the butler, might be a good way to maintain suspense and add a twist to the story. But if Colonel Prune only makes an appearance three pages before the end, it doesn't seem like much of a mystery. Or just too much of a mystery...
Anyway, as we're talking computer and technology guidance here (where creating mysteries isn't usually approved practice) I should probably try and wend my way back to the topic that was in hand a few paragraphs ago. Such as guidance for Microsoft products like Windows Phone 7 - for which our upcoming guidance presented an interesting set of issues.
Thing is, you see, this guidance is part of a series of scenario-based books that cover cloud-based services and the corresponding client applications. When we did the Windows Azure book, it was pretty easy to figure out the TOC. We needed to introduce Azure, introduce the fictional company that was building cloud-based services, and then explain how they did it. Yes, we needed to talk about what Azure is, what it can do, and how you program for it. But these are closely related topics that can easily be covered in the chapters that discuss each part of the overall scenario; such as using tables and blobs, authenticating requests, building responses, and managing the data.
We didn't need to talk much at all about the operating system (Windows Server), the coding languages and framework (C#, Visual Basic, and .NET), and the communication protocols (WCF) because these are all well known and fully documented things. Yes, there are Azure-specific issues such as instrumentation, data storage, and other factors; but these differences are fairly limited in scope and impact, and are easy to include in the individual chapters of the overall scenario. The major bits such as the way applications run, the use of worker roles, and all of the considerations about designing your applications are pretty much the same as when you have a big lump of metal and plastic in an air-conditioned room next door to your office.
And then we come to Windows Phone 7 (WP7). One of the major strengths of WP7 is that lots of things are just the same as in any other .NET application. The platform you program on is Silverlight (or you can use XNA if you like), the languages are the same (we use C#), and the whole development paradigm (Visual Studio and Blend) is just like programming for the desktop or Silverlight in a web browser. There's even an emulator you can use to run and debug your applications, and so it's really just another automatically familiar environment for building applications.
Except it isn't. Once you start to dig, you discover all kinds of things you need to understand and program for. For example, in a desktop application it makes no difference to you if the user switches to another application such as Outlook when the familiar "ping" announces arrival of a new email message. Your application just blithely continues in the background doing stuff. On WP7, when the phone rings or the user decides to read an email that just arrived, your application stops. And the operating system might even decide to close it down altogether, and without giving it the chance to do that "You may lose any unsaved data" dialog thing. So you need to know about application lifecycles and tombstoning.
And what about performance issues? Unless you currently use a very old computer, the phone is somewhat of a poor relation in terms of CPU speed and storage space. Don't expect a quad core Xeon or 2 TB of disk space. Yes, there's a very smart graphics processor, but you still need to worry about frame refresh rates, graphics caching, transitions, and other display-related stuff if you are doing graphics-intensive things or else it could end up looking like a 1930's Charlie Chaplin movie. You need to know how to use the onboard graphics mechanism, the frame counter display, and the correct way to manage bitmaps and graphics objects.
And then there's all the other wondrous capabilities such as location services, the camera, sound recording, the accelerometer, media capabilities, messaging interaction, gesture detection, Windows Marketplace, push notifications, and even vibration alerts. You can (and probably will) use all these in your programs, so we need to explain them as well. In fact, there's a host of exciting capabilities that you can use in WP7 to make your applications attractive and interactive. Though they do need to conform to the standard UI design guidelines and themes for WP7; so we need to explain these as well.
And here lies the problem. Instead of starting with an introduction to the WP7 platform, a few useful links to well-known technologies, and some blurb to keep the marketing people happy, we have tons of stuff to explain that is likely to be new to a great majority of developers. Such as how you can apply common design patterns; how you manage storage and communication over different types of occasionally-connected network connections; how you fetch, store, and upload data; and more generally how you think about the design and architecture for your applications. You need to manage power consumption, think about how and when the phone will be used, and make the UI usable for people like me with fat fingers.
So a brief "About Windows Phone 7" chapter followed by diving into the scenario of the fictional company and their shiny new WP7 application is not an option. There's just too much to think about, and it will make the chapters describing each section of the overall scenario way too complex and bulky. Readers would lose the thread (and even lose the plot) trying to constantly switch from design guidelines and technical reference to scenario implementation details in each chapter.
OK, so we spent a while trying to shoehorn the content into a structure and TOC similar to the other guides in the series to preserve continuity, but we finally had to admit defeat. We just didn't have the right TOC - we'd created it before we could actually see what the completed book would look like, and then tried to mould the content into it. We'd put all the socks, underwear, and sun creams into the suitcase before trying to pack the kettle and the big box of teabags.
The answer was to throw away the TOC and build a new one that made sense for the entire content. An introduction chapter that has the required marketing blurb, explains what a wonderful device WP7 is, and then sets the scene for developers. A pragmatic and focused second chapter that does all the design advice things and explains the issues you need to consider before you fire up Visual Studio. And, to provide the rest of the required guidance without breaking the flow of the main chapters, a series of targeted appendices that cover the development environment, the phone platform, the device capabilities, and other peripheral stuff. Now the remaining chapters that form the bulk of the book can concentrate on the fictional company's scenario, and how they built their application.
Yes, an appropriate TOC does seem like an obvious prerequisite that should already have a big black tick next to it before you start. But it's easy to just dive in and start building content for the parts you already understand, and then add more as you discover other nuances and requirements. Without getting a tick for your TOC at the start, you'll end up (like we did) spending more time trying to sort it all out later. Probably just as the publisher is banging on your office window demanding the final manuscript...