Random Disconnected Diatribes of a p&p Documentation Engineer
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...
As last week's babble seemed for some unaccountable reason to wander towards a science fictional theme, I thought I might as well follow up this week with something from my favorite (well, one of my favorite) sci-fi authors. I refer, of course, to the unforgettable Isaac Asimov. I got to thinking about his work while watching a TV program about how the Internet is shaping our lives, and how the future for young people will be influenced - and even (rather worryingly) - controlled by the social media sites and commercial content producers that inhabit it.
Asimov's famous character Hari Seldon, a mathematics professor at Streeling University on Trantor, developed the science of psychohistory, which effectively provides a way to accurately model the collective behavior of entire galactic populations over very long periods of time. Thus he could predict with unerring accuracy the major events that will befall each civilization; such as wars, plague, pestilence, and lack of Internet connectivity (OK, so I made that last one up).
But, anyway, until a rogue being appears on the scene, all is running pretty much according to plan and the regular appearances that his holographic automaton makes prove amazingly accurate. And there are some people who think that psychohistory could, in fact, be a reality and not just fiction. Adolphe Quetelet's "Social Physics" and John Xenakis's "Generational Dynamics" follow a similar theme, and there's even whole Web sites devoted to the science of "Cliodynamics".
Thing is, it seems that an increasing proportion of the population is influenced more and more by what they see on the Web. I'm personally not a twitterer or spacebooker, and I tend to avoid networking sites such as LinkedIn and the plethora of similar ones on the grounds that I'm too busy working with computers to spend my leisure time at the keyboard. I'm certainly not interested in what Stephen Fry had for breakfast this morning, and I'm quite content with having about 4,999,980 less friends than Lady Gaga.
Meanwhile, psychohistory relies on two axioms: the population whose behavior is modeled must be sufficiently large, and must be unaware that psychohistorical analysis is taking place. It's probably safe to say that the population of twitterers, spacebookers, diggers, stumblers, and the like is sufficiently large; and I'd imagine they're too busy twittering and spacebooking to notice that we're watching them. So the axioms should hold. Therefore, what can we actually predict? How about:
All I need now is my holograph likeness, a glass box, and a smoke machine...
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."