How does subway mapping work? Essentially, once you are familiar with the basic concepts of the subway, you can easily go wherever you want. You don't need a lot of other informatoin. When you see a familiar sign in a city with a subway (like for the T in Boston or the Métro in Paris), you know immediately where you are in relationship to where you want to go.

Take Boston. Suppose your hotel is near Copley (Green line) and you are at Airport (Blue line). It’s easy to figure out how to get close to your hotel: Take the Blue line to the Green line connection and go to Copley station. You might know nothing else about Boston.

http://www.mbta.com/schedules_and_maps/subway/

Is there any reason why technical documentation can’t be like that? The surface area of an SDK can cover a lot of ground. You can combine SDK types in ways that are nearly infinite. In most cases, however, there are fairly predictable ways in which functionality is used. These would be the subway lines or routes.

Here's an example: You are using Team Foundation Server (TFS) because you like the way it manages your bugs. You are familiar with the basic concepts of bugs, which in TFS are a type of work item. Let’s say you get the idea to customize the look of the bug. You extend that idea to automatically create the bugs when a some event happesn. In other words, you know where you are, bugs, and you know where you want to go, automatically creating bugs. You would not need to know that the automating information is in the SDK. And, you don't need to know much more about the SDK.

I’m not sure there is a perfect way to do this in documentation, but John's initial effort here seems to be a step in the right direction: http://blogs.msdn.com/johnkenn/archive/2007/02/27/windows-mobile-sdk-documentation-navigation-experiment.aspx. Notice how John’s graphic resembles a subway map. Isn’t this more intuitive than just a black-and-white table containing information about the subway stations and connection times?

Documentation seems to encounter this problem a lot. For example, customizing TFS is part of the core documentation and ships with the product. On the other hand, the SDK ships separately as there is a perception that not all TFS customers want or need the SDK, which is for extending the functionality. Customizing the product is a slightly different route than extending the product. The ideas are related. They have might have subway stops in common.

This is why we need something like a subway map.  You can walk on at the “customizing Process template” stop in the TFS Help (like a stop on the Red line), but you can see from that map that you need to be at Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItem. That's in the TFS SDK (i.e. on the Green Line). Hopefully, it would be easy to see that you need to go download the TFS SDK so that you can get to Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItem.

Most users don't immediately jump to a top-down hieararchy in their mental mapping. The subway map provides a tool that says you are here, and this is how to get to your destination. Find where you think you want to go and use the map to chart a path close to there.