Hands-Off Labs

It seems to be a general rule now here at p&p that every guide we produce must have an associated set of practical examples so that users can get their hands (and keyboards) dirty playing with the technologies. It's almost like we're worried that our readers won’t believe the stuff actually works; or might think the text of the guide was dreamed up by the marketing department during one of their going forward, 360 degree, base-touching idea showers.

It's weird that I always dread the moment when the project manager suggests it's time to start on the Hands-On Labs (HOLs) for the guide we just shipped. The work involved in producing them always seems to vastly exceed any benefit users may get from them. Yet, once we get under way I really do enjoy working to the highly structured and predefined format. OK, so it takes an age to get the screenshots, the code, and the order of tasks correct; never mind the regular changes to the plan and the content. But it usually goes much better than I initially feared, stuff tends to work more easily than I expected, and it often comes together more quickly than I originally envisaged.

As you may have guessed from this pre-ramble, I'm doing HOLs at the moment; this time for the Windows Azure Hybrid Applications guide we recently released. And despite pages of instructions for setting up Service Bus, ACS, Traffic Manager, Azure Connect and more, the stuff is working as it should with only the minimum level of cursing and swearing at the technologies. We're well over half way through the ten labs, and still working to the original plan. Surely something must go wrong soon...

But where I am struggling is with the complexity of the technologies and the examples. Working with hybrid applications that use a wide range of networking services over the Internet means that the opportunities for simple one-line explanation of the operation are few and far between. Now combine that with features such as federated authentication, a fully architect-compliant application design that incorporates interminable levels of redirection, dependency injection, two MVC websites, WCF services, reliable messaging and connection retry mechanisms, and a multi-level Entity Framework based data model.

The result is that every step requires additional explanation of what the code does, and why. The rules for HOLs suggest each step should be a single instruction followed by a code listing or a screenshot, and that there should be minimum distraction from the steps themselves. Yet I'm finding I need to have up to three or four individual instructions in each step to be able to achieve something worthwhile in less than 20 steps, and each one seems to require a paragraph or more of explanation in a background box. And all this while complying with our new accessibility standard.

Users should be able to complete a HOL exercise within 30 to 40 minutes, and a complete lab in under an hour. Maybe that's possible if the exercise is how to create a class file in C# or write a WCF service that returns "Hello World", but it sure takes a lot longer to show users how to configure Service Bus and ACS when connecting a new partner organization to your existing hybrid application. Or to deploy the application to multiple datacenters, along with the data in SQL Azure and DataSync configured between all the instances.

What's mostly of concern, however, is the amount of time users of the labs will actually need to devote to understanding the theory and background to the exercises. Each lab has an overview with a schematic of the architecture for the example and the exercises, and then each task explains the objectives and the results. Meanwhile many steps have a couple of paragraphs explaining what's happening at each stage, and the code listings are interspersed with descriptions of how they work.

I guess I include all this extra content because I can’t see the point of someone going through the exercise just blindly following the instructions in the steps, without actually gaining any understanding of why they need to do it or any appreciation of how it all works.

But if our users end up spending more time reading than they do clicking and typing, have I actually created Hands-Off Labs?