There is strange bit of information/lore that often gets presented to us writers by our publishing teams or other sources. Supposedly, based on metrics like page hit tracking, using the Table of Contents as a primary means of navigating MSDN content is pretty uncommon. Far more people use Search, by factors of like 5:1.
Is this really true? Or are the metrics that are trying to capture overall MSDN navigational usages inaccurate or otherwise missing out on capturing the true navigation tactics that developers are using to try and find our MSDN content for Silverlight?
Such a low usage or regard for the Table of Contents as a way to navigate documentation is confusing to me as a writer of developer-oriented content. It’s perhaps a little worrisome. It makes me feel like our audience isn’t really using the MSDN documentation to the best effect. Here are some of the reasons I feel that way. I’ll divide these up into general statements about how to find things in the overall Web that might include MSDN results, and those that are fairly particular to MSDN, MSDN Search, and material that the Silverlight SDK team or other contributors write for MSDN.
Edit to add (10-19-2010) – probably something that is leading to lack of Table of Contents usage is the MSDN Lightweight View’s implementation of the table of contents construction. I do not like what the MSDN team did here, user-experience-wise. The Lightweight View TOC shows only the following: the immediate peers of the current node, and the “breadcrumb trail” of each parent topic recursively to the TOC root. In my opinion that is not a Table of Contents at all, and it’s really very non-browsable for a variety of reasons. So, what to do? Engage the Classic View! This will restore the somewhat more conventional view of a table of contents, along with other presentation characteristics that I generally prefer to the “new design”. The one unfortunate side effect is losing the tabbed examples, but that’s a subject for another blog post …
Don’t know how to get to Classic View, and/or you’re stuck in the default Lightweight? (Or maybe you didn’t even know there was such thing as Classic View?) Here’s how to get Classic. Find the Preferences link on the bar in the far upper right of any MSDN Library page. Click it. This displays a Choose View page. Select Classic View and click OK. The view will persist across sessions (so long as you are cookie enabled). You can change it back at any time, although the exact UI to do so varies in each view.
General to the Web
A TOC can provide a near neighbor, to answer fuzzy questions
Sometimes, you are trying to answer a question that is pretty basic and maybe downright naive. You fire off a search string and follow a result, but on scan of that result topic opened up you can tell that your question isn’t going to get answered right there. However, you have the suspicion that the topic is part of a set of topics wherein one of the other topics might answer your requirement. Sometimes if you read the topic linewise you can get to such a related topic by a See Also or following test-inline links, but not always.
If a TOC or something like one exists, usually I find it more efficient to examine the near neighbors of the current topic and their titles. Metaphorically, it’s like you’re already in the neighborhood, you’ve already parked the car, you’re just a few house numbers off. May as well walk – a couple of mouse clicks, and maybe a BACK button here and there, could well be the more efficient way to find your answer at this point than is wordcrafting a completely new search string, typing it, and poring over another long results list.
A TOC is better for exploring
It’s true that as a user of a documentation set you don’t always have time to just explore. But, sometimes you do have time to explore and want to investigate questions that you have in a vague conceptual sense, rather than an I-must-solve-problems-today mindset. Maybe you got into the document set via a search for a specific question. But, perhaps what you read in a search result suggests another question that you hadn’t thought of before; maybe you didn’t know how to frame that question as a concept or by using the relevant terminology until you read that initial topic. Random walks like this work much better in a TOC when available, and particularly if there’s a You-Are-Here sync feature in that TOC so you can see the displayed topic’s position in that TOC.
A TOC is a useful quality assessor of a full docset, even if you don’t use it for navigation
Maybe you arrive at a search result, and you’re reasonably happy with that result answering your immediate question. So now you’re interested in knowing whether that site or document set is a worthwhile authority for answering future questions you might have about that product or technology. Perhaps in the future you can search by domain or otherwise scan results and bubble that site’s contributions to the top.
That assessment can be made most quickly on document sets that have a table of contents, or at least for sites that have a comprehensive sitemap. You can expand the TOC and scan over the titles and get a sense of whether they are structuring the content in what seems like a sensible way. And based on that structure you also might get a sense of depth of coverage.
Let me give you an example. If I want to learn about Silverlight animation, I might go to a result on a particular site. But now I see that they have exactly one topic in their document set that deals with Silverlight animation. I’ll be suspicious at this point – how can they cover any reasonable amount of depth of the Silverlight animation concepts in just one document, especially if the browser scrollbar hints that the document isn’t really that long? I’ll be more willing to invest time in a document set that has multiple topics about Silverlight animation, and has taken the time to structure and scope their document set, as revealed by looking at the titles and structure of their TOC.
A TOC can be a spatial map to find your way BACK at some subsequent time
You can’t bookmark everything. Ideally you find some root of a documentation set and bookmark that as a future starting point. Otherwise, you end up having to basically write your own all-things-TOC in your browser’s bookmarking UI to maintain sense in your bookmark organization.
Given a known starting point like a bookmark to a root of a documentation set, there is something reasonably close to spatial in the tree structure of a table of contents. Humans are spatial animals. We can conceptualize the “shape” of the TOC, remember some particular names in the waypoints of the various titles, visualize the twists and turns of which collapsible entries we opened, recall some wrong turns we made and won’t make again, and so on. Maybe you won’t get the hang of the “map” of any given TOC of a document set on the first time in. But maybe by the tenth time, or the hundredth time, that mapping starts to make sense in our brains, and you can run through that TOC rather than walk. At that point, using the TOC can definitely challenge even a well-crafted search string plus a decent search provider for providing a good result against a given question quickly.
Any Search results page is a moving target
Search results pages change over time. Maybe what was result #3 today is result #41 tomorrow for the exact same search string. If so, you won’t find the same topic with the same search nearly as efficiently, even if you remember the exact search string or even if you bookmarked it. Search results change just because, on the whim of the provider and in response to what data flies in and out of the web. TOCs change too, but they tend to change more deliberately and only for major release cycles.
If you follow TOC links, you have visual consistency in what you are getting
Too often, you have result summaries that visually equivalent in the search provider’s result page, but lurking behind each result is something completely different that takes a “reset” of your eyes and brain every time you click each result link. Result #1 is a blog post. Result #2 is someone else’s blog with different colors and fonts. Result #3 is a white paper that is 42 pages long. Result #4 is some deeply nested MSDN reference page. And so on. If you actually click in and Back through a sequence of more than a few results, it’s just mentally and visually tiring.
I find this to be particularly true of using the MSDN Search, even if you do use the filters to try and keep results within the Library. In contrast, when you click through a TOC, you’re getting information that you know fits together somehow, plus that information is presented in equivalent visual formats that you can scan quickly without so much eyestrain.
No version bounce
This is a problem that’s endemic to Microsoft MSDN content. I’ve blogged before about things you can do to not get all tripped up in searches for terms or API names that exist in multiple versions of the full .NET Framework platform plus Silverlight plus whatever else comes along that overloads that same API name or concept string. But sometimes, it just happens that your result list is all crossed up in different technologies and versions, and it’s hard to tell that just from result summaries. This can really get frustrating because how the results line up will behave differently on every possible string search. A lot of times you have the “version box” to the rescue when you get version-bounced and follow a result to the wrong document set, but sometimes you don’t. For example there are lots of Silverlight and WPF versions of what is really the same conceptual topic focus area, but because of publishing pipeline reasons there’s no known relationship between those topics and no version box exists. If you use the TOC you are guaranteed to be immune to version bounce. That’s the main reason I often use the TOC even to find managed APIs using alphabetization order in a namespace, by walking the seemingly daunting “.NET Framework Class Library for Silverlight” node through namespace-class-member.
MSDN writers will write and structure our content based on the assumption that a TOC exists and is visible
Our publishing source control system is actually structured around a tree view that completely parallels a subset of the eventual published MSDN TOC. While ideally the tools we use to write shouldn’t affect the output result and taint how the eventual reader interprets our output, I’m pretty sure that the TOC metaphor is definitely shaping our instructional design. For example, I might place a more detailed concept like “Custom Dependency Properties” as a child node of a more general “Dependency Properties Overview”. The parent topic would typically have a paragraph that summarizes the child, including a See Also to that child. But even so, as I write up the material in that child topic, I do so with the idea in the back of my mind that users can SEE that they’ve got this TOC available for orientation. I work with this theory that if my users are not understanding the concepts in one of my more deeply nested child topics, the right instructional design concept for both me as the writer and for my readers as the audience is that the reader should go to the parent topic by using the TOC, read that topic, get oriented and educated on the basic concepts that are blocking understanding, and then return to the original topic by using the TOC
So there it is. My scattered and marginally Luddite defense of the value of a Table of Contents for proper understanding of developer-oriented documentation.
Anyone care to chime in with (hopefully more articulate) support or rebuttal on the value of having and using a Table of Contents in a documentation set?