TOC Tick

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...

Comments

• Anonymous
  September 12, 2010
  "I'm sure my wife won't mind me publicizing the fact, but she is rubbish at packing stuff."My partner suffers from "Space Cancer".  The Goal?  Fill up the biggest space with the smallest number of items.Which means that I do the packing of the car when we travel somewhere.