I really appreciate cross-links in documentation. I think there’s value in both automatically-generated (e.g. Javadoc’s ability to mark up a function signature with links to all of the classes involved) and manually-generated (“If you want more information on how this interacts with threading, read The Foo System and Multithreading“) cross-links.
There’s one system of cross-linking that I’ve only seen on MSDN so far: links to other versions of the class or method being documented. Take this pedestrian method as an example. The default version of this page is for .NET 3.5, which is the current version, but a table on the right provides access for .NET 1.1 through .NET 4.0 as well as Silverlight. Version cross-links also make version information part of the ambient information of the universe, making it easier to find and correct false assumptions.
Many projects don’t need multiple versions of formal documentation active at once. For the ones that do, this is a killer feature.
Yeah, I agree. Cross-links to future versions of documentation are particularly useful when a new version of a product comes out, and the top hits on google searches are still for the old version. I had this problem for months after Python 2.6 came out–a google search for a python function always took me to the Python 2.5 doc for that function, and since the format of the documentation url’s had changed, there was no easy way to go from there to the 2.6 documentation for it.