A Relentless Paper Chase (aka Painting Windows Azure)

Here in Britain we always used to refer to a job that was never-ending as "like painting the Forth Bridge." It came about because the people who paint the huge and magnificent railway bridge over the Firth of Forth in Scotland reportedly start at one end and it takes so long that, when they reach the other end, it's time to go back and start all over again.

However, with the new type of paint they used this time it seems they won't need to do it again for 25 years (see this BBC story). So now we need to find another suitable phrase to describe endless tasks that are overtaken by circumstance. After a couple of years working on documentation and guidance for Windows Azure, I propose we replace it with "like documenting Windows Azure".

See, here's the problem. When applications came in a pretty box with some floppy disks or a CD they tended to have a strict release schedule. You could write a book about Microsoft Access 1.0 (in fact, I did) without worrying that the product would be completely different before you could get your draft through edit and sent to the printer. Even when documenting features of the operating system, such as Active Server Pages, you could reckon to hit the streets well before they released a new version of Windows Server.

But now that we are all web-enabled and Internet-driven, it seems like us poor documentation engineers have almost no chance of keeping up. Product teams can drop in new features any time they like, and entirely change the UI so that our step-by-step guides make no sense at all and all our screenshots are out of date by the time we get the pages onto MSDN. I mean, we're just putting the finishing touches to the third update of the p&p guide "Moving Applications to the Cloud" and so much has changed since we released the last update (July 2011) that we've ended up almost totally rewriting it.

As well as adding in new content around Cloud Services, such as updated configuration techniques and our own Transient Fault Handling and Autoscaling Application Blocks, we widened the migration scenarios to include Windows Azure Virtual Machines, Web Sites, hosted SQL Server, and new connectivity options such as Virtual Networks. We also added in more guidance about choosing the appropriate migration path through the ever-increasing list of hosting options. And, of course, we had to rename everything that's now got a shiny new moniker (think "SQL Azure" and "Windows Live ID").

We're really pleased with how the guide has evolved, and confidently expect the new content to be even more useful to architects and developers considering migration of on-premises applications to Windows Azure. But, at the point where we expect to release, there'll obviously be yet another update to the Windows Azure SDK that will impact the sample code. And then in the next portal refresh they'll probably add another bunch of new stuff so we're out of date again, before we can even get it to the printers.

Meanwhile, the "Hybrid Applications" guide we released only six months ago, and the associated Hands-on Labs we released in May this year, is already starting to look a bit out of date because there's a brand new web portal; new services such as Virtual Machines, Web Sites, and Virtual Networks; and a whole new caching mechanism. This guide's on the list for an update, but we have the second guide in the series, "Developing Applications for the Cloud" to update before then.

In fact I only just discovered that I'm now a member of the "sustained engineering team" here at p&p. At first I was a bit concerned it suggested that, up till now, we only engineered occasionally - when we weren't busy doing something else. Yet I've always considered myself to be a "documentation engineer" because creating guidance is a task I do all day every day; and it has just as strong a relationship with "real" engineering as writing code does.

Documentation engineering is like building a luxury motor car. You sculpt an attractive and intuitive exterior and interior, design and build the underlying structure that connects all the parts together, manufacture (or source from third parties) the components that actually make it work in the most cost effective way, and assemble the whole thing into a package that people will want to use every day.

The problem is that, unlike a car, you can't just paint your guidance a different color, put some fancy alloy wheels on it, and stick a new badge on the back every six months. You actually do have to re-engineer it each time. I did suggest to our project manager that he wander over to the Windows Azure development team's offices and hit them with a big stick until they promised to stop changing stuff. But he said that probably contravenes some company policy.

Maybe, instead, we can get hold of some of that 25-year paint in time for the next update...