One of the joys of being a documentation engineer is the variety of projects I tackle. At the moment I'm sharing my time between two projects at diametrically opposite ends of the complexity and target audience spectrums. It even seems as though it requires my brain to work on different wavelengths at the same time. It's almost like a Rainbow Coalition, except that there's only me doing it.
For the majority of my working week I'm fighting to understand the intricacies of claims-based applications that use ASP.NET, WCF, and WIF; and to create Hands-On-Lab documents that show how you can build applications that use tokens, federated identity, and claims-based authentication. In between I'm writing documents that describe what a developer does, the skills they require, and the tools and technologies they use for their everyday tasks.
What's worrying is I'm not sure I really know enough about either of the topics. Claims-based authentication is a simple enough concept, but the intricacies that come into play when you combine the technologies such as ASP.NET sessions, browser cookies, WCF, WIF, ADFS, and Windows Azure Access Control Service can easily create a cloud (ouch!) of confusion. Add to that interfacing with Windows phone and, just to make matters even more complicated, SharePoint Server, it's easy to find yourself buried in extraneous detail.
What became clear during research on these topics was why some people complain that there is plenty of guidance, but it doesn't actually tell you anything useful. I must have watched a whole week's worth of videos and presentations, and got plenty of information on the concepts and the underlying processes. But converting this knowledge into an understanding of the code is not easy. One look at a SharePoint web.config file that's nearly 1000 lines long is enough to scare anybody I reckon. Simply understanding one area of the whole requires considerable effort and research.
Contrast that with the other task of describing what a software developer does. If you ask real developers what they do, chances are the answer will be something like "write code" or "build applications". Yet when you read articles on how development methodologies such as agile work, you soon come to the conclusion that developers don't really have time to write code at all. Their working day is filled with stand-up meetings, code reviews, customer feedback consultations, progressive design evolution, writing unit tests, and consulting with other team members.
And what's becoming even more evident is that everything now is a cross-cutting concern. At one time you could safely assume that someone using Visual Basic was writing a desktop application, and that the developer using ASP.NET was building a website. Or the guy with a beard and sandals was writing operating system software in C++. Now we seem to use every technology and every language for every type of application. Developers need to know about all of them, and weave all of the various implementation frameworks into every application. And find time to do all that while writing some code.
For example, just to figure out how our claims-based examples work means understanding the ASP.NET and C# code that runs on the server, the WCF mechanism that exposes the services the client consumes, the protocols for the tokens and claims, how ACS and ADFS work to issue tokens, how they interface with identity providers, how WIF authentication and authorization work on the client, and how it interfaces with the ASP.NET sessions to maintain the credentials. And don't get me started on the additional complexities involved in understanding how SharePoint 2010 implements multiple authentication methods, how it exposes its own token issuer for claims, and how that interacts (or, more significantly, doesn't) with SharePoint groups and profiles.
At one point in the documentation about developer tasks, I started creating a schematic that maps development tools, technologies, and languages onto the four main types of application: web, desktop, cloud, and phone. It starts out simple enough until you realize that you forgot about Silverlight and XNA, or still need to find a slot for FxCop and the Expression Blend. And where do you put the Microsoft Baseline Security Analyzer? Meanwhile, Visual Studio seems to be all things to all people and to all tasks. Until you try to divide it up into the full versions, the Express editions, and the special editions such as the one for Windows Phone or the add-ons for WIF and Windows Azure. I don't think anybody has a screen large enough to display the final schematic, even if I could manage to create it.
And just like Rainbow Coalitions in government, it sometimes seems like there are lots of different actors all trying to present a single face to the world but, underneath, all working to a different script. Should I use Razor in WebMatrix for my new website, or MVC, or just plain old ASP.NET Web Forms? Is WPF the best technology for desktop applications, or should I still be using Windows Forms? Or do it in Silverlight in the browser. And in which language? It's a good thing that, here at p&p, we provide plenty of guidance on all these kinds of topics.
Still, at least I can create my technology matrix schematic using all of the colors of the rainbow for the myriad boxes and shaded sections, so it actually does look like a rainbow and provides a nice calming desktop background - even if it does nothing else more useful.