I've occasionally heard developers talk about a "code smell" - subtle indications that lead to the uneasy feeling all is not well with the source code for some application (as opposed, I guess, to the not unknown opinion that everybody else's code stinks). I wonder if there are similar easy-to-miss signs that some piece of documentation or guidance you've been slaving over for weeks is not quite all it should be? Is there an equivalent "docs smell"?
One of the challenges of working in the patterns & practices team is targeting the guidance I create at a level of technical capability appropriate for users; and gauging the relevant experience and knowledge that the users we do target will already possess. Much of the problem seems to relate to the huge breadth of technologies available and the increasing complexity of techniques that are now becoming common. Our primary aim is to provide guidance for users of Microsoft technologies in real-world scenarios. We don't teach people how to write a Hello World application in Visual Basic, or how to use CSS to style a web page. Instead, we aim to demonstrate how development teams, system administrators, and software architects can get the maximum benefit from applying enterprise-ready software, techniques, and solutions.
We do our best to help professionals build applications and services that fulfil meaningful and useful tasks. However, everyone needs to start somewhere. For example, we can't just assume that every user of Windows Identity Foundation (WIF) is already an expert in building Windows Communication Foundation (WCF) services. It may be that the only time they WIF is when building ASP.NET applications. And, conversely, it may well be that someone highly experienced in building web services with WCF has never seen an ASP.NET GridView control. Or know what Razor is.
Of course, Razor is a relatively simple technology to learn. In fact, I've been working on a guidance project for another group (not p&p) that covers it in some depth. And, as we assume that it's a technology primary aimed at newcomers to web development (which may or may not actually be the case in real life), we explain a lot of the theory behind the HTML techniques we demonstrate, and other related web development and data management topics as well. Except we use only C#, including generics and many of the latest fancy syntax shortcuts, without explaining these. OK, so we can't cover everything in one go, and have to make some assumptions on the existing knowledge of the reader. Yet (sniff, sniff) many developers I know who are just starting out with web development use Visual Basic...
A particular topic where this difficulty in accurately targeting guidance is relevant is one of the p&p projects I'm currently working on. We've already produced several related guides on Windows Azure, Moving to the Cloud, Windows Phone 7, and the use of Claims for Identity and Authentication scenarios. Many of the techniques used in the guides and the sample applications are common across these areas of development. However, they are not generally well-known topics, and include a plethora of new terms and technical jargon. The result is that some potential users of our guidance may have difficulty finding the relevant content; especially if they are not already familiar with the technology space.
So how do you counter this issue? We've got some ideas that will improve the visibility of different parts of the content and provide a more definitive road map that will help potential users find the relevant parts. One is to provide a FAQ-style list of topic areas and subtopics that narrow the view into the appropriate areas of the content. Another is to create introductory guidance that steers users into the required area by helping them to understand the different parts of the content when starting from a lower level of prior knowledge.
This doesn't, however, solve the problem of "findability". Even when we apply fancy SEO techniques to the online content, it is unlikely to appear at the top of a search engine results page. These use all kinds of rules, including preference for the most recent content, the presence of keyword repetition, and matching phrases within the topic headings; all of which tend to reduce the prominence of guidance that is created in a form primarily suited to printing as a book. This means blog/forum posts and articles that have just been published are more likely to appear before any of our online content. The result is that the poor users, searching for help on a topic with which they are not already familiar, will find short snippets of information that is often not helpful when starting out with a new technology (or which, in some cases, is just plain wrong).
A typical example of the findabiity problem I encountered was when researching the different patterns for authenticating a service call using a combination of Active Directory Federation Services (ADFS), Windows Azure AppFabric Access Control Service (ACS), and – of course - WIF. So far I've identified around a dozen different architectural scenarios and service request patterns for this, several of which seem to be almost impossible to implement or to actually make work. Or describe in a meaningful way to newcomers. Even helpful blog and forum posts such as "WIF supports SAML tokens but not the SAML protocol" may not be terribly useful to these users as they struggle to understand the technologies. OK, so I can provide overviews, definitions, diagrams, and all the usual guidance stuff for those that stand half a chance of being implementable. Though I'm surprised that Visio didn't pop up an error dialog to say it had run out of arrows while I was trying to sketch out all the schematics.
And when I finally came to write the questions and answers bit for the end of the chapter, I realized that I was OK asking the questions but then I couldn't decide which of the multiple-choice answers was correct. Depending on which blog posts I read, how I tilted my head, and whether I closed one eye, all the answers seemed - at least to some extent - to be correct. Maybe this is actually a good example of a "docs smell", though I suppose I can't really really blame Windows Identity Foundation for that.
But it sure is a handy technology for creating pun-filled blog post titles...