About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

It's clear that a high IQ alone probably won't get you very far in life--unless you find a job taking intelligence tests.

Steve Sampson



Navigation





<November 2017>
SMTWTFS
2930311234
567891011
12131415161718
19202122232425
262728293012
3456789

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 11/17/2017

Totals
Posts - 2460
Comments - 2563
Hits - 1,999,326

Averages
Entries/day - 0.47
Comments/entry - 1.04
Hits/day - 380

Updated every 30 minutes. Last: 8:04 PM Pacific


  01:49 AM

Most of what we write is published in the MSDN Library, which has documentation of all sorts for developers (the D in MSDN) who use the Microsoft platform. A recent estimate is that there are about 2.5 million pages on the MSDN site as a whole, with the bulk of those in the Library.[1]

If you open the MSDN Library and happen to be in (or switch to) Classic view, you'll see that the Library has a table of contents (TOC):





Consider for a moment the idea of a TOC that lists around 2 million pages. If it were your job to organize 2 million pages, how might you construct the TOC? And if you're a developer looking for information about a specific task, how useful would you find a TOC that represents that quantity of information?

Periodically the question comes up whether the TOC — in particular, this TOC — is worth the effort. As you can imagine, it is not an easy job to pull this thing together. About once for every major product cycle, we get together and contemplate what to do about this monster.


Should we show a TOC?

The first question is whether we even need it. We know from user surveys that a very small percentage of readers use the TOC as a primary entry point into our documentation. Most people get to specific documents either using search (external or within MSDN) or via links in other documents.

The thing people seem to like best about the TOC is the "sync" feature — once you’ve landed on a topic, the TOC is synced automatically so that you can tell where you are. For example, click this link: Cross-Page Posting in ASP.NET Web Pages. If you're in Classic view, you'll see that the TOC has opened to show you were you are:





This benefit of the TOC — context for where you've landed — is considered valuable enough that even tho the full TOC does not appear in Lightweight or ScriptFree view, there's still a version of this "where am I" display in both alternative views. Here's Lightweight:





And ScriptFree:





Not long ago, I posted a question about this issue of TOCs on the TechnicalWritingWorld website. ("Do you use TOCs to organize online content?") There were some good replies. Given the size of MSDN, Richard S suggested the analogy of a TOC for YouTube and how this would not really be helpful to find specific videos. Mark Baker suggested that to the extent that a TOC was useful, it represented a failure of both the search facility and — this part was particularly thought-provoking — a failure to create documents such that each could supply their own context and useful links. (I'm sure that people would argue this point, but I like the idea that if you're going to do without a TOC, you need to structure the actual content accordingly.)

What people don't seem to disagree on is that having multiple ways to navigate content is good. This is, in effect, where we tend to land on the issue of creating the TOC. Even if it's not a primary entry point for most people, it has enough benefit to still be worth exposing to users.


How should we organize it?

Assuming we are going to create a TOC, how do you organize a TOC to cover this many pages? If you're writing a book, the TOC is in effect an outline for your content — that is, an overall plan. The MSDN TOC is not really the same thing; it's not an overarching plan for a single massive doc set. The library is an aggregation of a bunch of different individual doc sets — different platforms (client, web, phone), products (.NET, Silverlight, Windows Mobile), documentation approaches (product documentation, APIs, articles, books), and so on. Each of these is organized according to its own plan. The MSDN TOC is really more of a catalog for all these different things. Yet it still has the style of a TOC — hierarchical and organized in a way that (we hope) makes some sort of sense.

In the current iteration of the TOC, a general notion is to organize according to development platform, kind of:





Note the high-level nodes for .NET Development, Office Development, and Web Development. But even this seemingly high-level principle doesn't really work out. For example, the Design Tools and Development Tools and Languages nodes pertain to Expression and to Visual Studio, respectively.

This illustrates one of the fundamental problems we wrestle with each time, namely how you organize information in a TOC when the information doesn't neatly lend itself to hierarchical classification. As far as we know, there is no satisfactory way to try to put platforms, tools, programming languages, technologies, specifications, etc., into a consistent, top-down structure. (Not to mention that each individual development team tends to argue that their particular thing, whether product or book, should be placed as high up in the hierarchy as possible.)

We've changed our collective mind with each release about how to organize the information, and any given approach has passionate advocates. But the fundamental truth of TOCs is that there is no one right way to organize them. We could probably agree (mostly) that some approaches are better than others, but we'll despair of ever finding the one true way.

Even within the node for any given product this tends to be true. There are general organizing principles for TOCs which are familiar from organizing books. For example, content within a node is often listed with the introductory material first, but this quickly peters out and becomes chunks of feature-related information. Here's an example:





Other benefits (mainly to us)

Even if we didn't show the TOC to readers, we get benefits from it. At low levels — that is, for individual products — the TOC has the same function as it does in books, namely an overall plan. This helps us define the story we want to tell users about our products, which in turn can help us figure out if we have holes in that story. (Short answer: yes, we do.) And at the higher level, the TOC becomes a tool to help keep track of the content that comes into MSDN from all the different partners — what are we getting, from whom, and how does it relate to the rest of the content?

I'm curious whether people have ideas about the MSDN TOC, either in general or specifically. If it went away, would people miss it? And are there benefits to having the TOC that we should be made aware of?


[1] This is a swag-ystimate only; not warranted to be suitable to any purpose, etc., etc. It's a surprisingly difficult problem to get an exact count of the site contents

[categories]   , ,

[4] |