The (Non-political) Third Way

One of the major advances in politics in recent years has been the evolution of “The Third Way”. You know the kind of thing: Given a choice between two approaches to a problem, neither of which are politically palatable, politicians invent a “third way” that relieves them of the requirement to choose either of the two undesirable outcomes. Of course, in reality, there are only two realistic options, and “the third way” usually involves doing nothing that resolves the issue or makes any real difference.

However, in the real world where we IT documentation engineers live, it seems there is a third way that actually does resolve the problem of a choice between two seemingly incompatible and undesirable options. In fact, in our current project, we’ve taken advantage of this ground-breaking technique in an effort to provide better guidance to our readers.

Faced with the requirement to create guidance around Windows Azure hybrid application integration (a topic I’m resolutely attempting to get recognized as “hybrigation”), we examined the two obvious approaches. We could base the guidance on the actual technologies available and used in the sample application that accompanies the guidance, or we could make the guidance more generic and useful by focusing on segregated categories of the challenges encountered in hybrigation using a series of generic scenarios.

My regular reader will know that I’m a fan of scenario-base guidance that addresses the widest audience, and guides readers towards the most suitable technological choices based on requirements, tradeoffs, and constraints. In other words, we take a common problem area such as communicating between an Azure-hosted application and an on-premises application, and research the individual scenarios based on typical requirements and hardware / software / environmental constraints. For each typical scenario, we describe the appropriate technologies and enumerate the advantages and limitations of each one so that readers can choose the most optimal solution for their own situation.

However, this approach may not take full advantage of the sample application that the development guys sweated blood creating. So we add some explanation of how parts of the scenarios previously described are implemented in the sample. But that only demonstrates a few of them, and these may not be the ones most applicable to the readers’ own situation and requirements.

The other option is to align the guidance with the sample implementation, and base the contents on explaining how it was designed and built. This is perfect for readers who want to build the same type of application that uses the same technologies and runs under the same hardware / software / environmental constraints; which is, of course, unlikely. But there are reusable chunks of code in there, so it is of value to a proportion of readers that need to tackle similar challenges.

Somebody famous once (nearly) said “You can teach all of the people some of the time, or some of the people all of the time, but you can’t teach all of the people all of the time.” It seems to be true, but only until you discover “the third way.” What is it? Well, dead easy really. You just do both. Explain how the sample application works, but include in the description the options that the application designer considered, the range of technologies that are available, and why they chose the approach they did. Then show how they implemented the chosen approach.

Ah, you say, but where did the generic scenarios go? Well, you can segregate the description of the application design and implementation into the different challenges, such as cross-boundary communication or data synchronization. And then tag onto the end of the guidance a set of appendices that investigate a wider range of general scenarios for each of these challenges. Readers can use the first part of the guidance to understand the design process of the sample application and the choices this involved, but also read the more comprehensive list of general challenges and scenarios to find solutions and advice more closely tailored to their own environment and requirements.

So readers get the best of both approaches. They learn more about both the design and the implementation of the sample, and also the other solutions that are applicable under different conditions. The only trouble is that we documentation engineers have to do twice as much work. But I suppose it keeps me from having too much spare time for writing rambling and semi-coherent blog posts. Or from continually inventing new words...