Illegibility Of MSDN2

Looks like MSDN2 went overboard in their zeal with printer-friendly pages. For example, head to Extending ASP.NET Health Monitoring in Internet Explorer and go to File | Print Preview. Here’s what you see:

That’s just impossible to read. Printing from Mozilla or Opera doesn’t help. In Opera MSDN2 falls apart. If I come across a subject I know I would need to take time to digest, I print it. With the current state of MSDN2 it’s not very feasible.

My suggestion to the content strategists and developers on the MSDN2 team is to drop this monkeying around with injecting URLs. What beats me is why nobody on the MSDN team has bothered to actually print a page of documentation to see this ugliness.

Which reminds me… I’ve been a big proponent of print style sheets all along, and I’ve been using a CSS technique to add URLs to links (see Make Every Web Page Printer-Friendly). It works only in browsers with decent CSS support (*cough*). Seeing what they’ve done to MSDN, I dropped my little CSS hack. The problem is MSDN links are ugly, long and cryptic. They easily span half a page which ruins the copy when printed. Enough of that.

While we’re on the subject of legibility, I’d like to point out how raw MSDN2 still is. Most of today I’ve been digesting Health Monitoring in 2.0 (hat tip to Scott Allen) and finding such pearls as “enable event buffering by setting the buffer attribute to false” or that buffer applies only to SqlWebEventProvider (wrong: it also applies to MailWebEventProvider. See Buffering ASP.NET Health Monitoring Events). And why do some pages have VB sample code, but no C#, while other pages are fine?

It seems like the doc team is still catching up to .NET 2.0 themselves....

I wouldn't mind any of this if it weren't only days away from an official release. But since VS2005 and 2.0 have shipped they really need to get documentation in line.

I can sympathise with these guys. My experience is that users will print large documentation (more than 1 or 2 pages) and read it offline. Of course in this scenario you loose all of your link context and it can be difficult to source links, samplke code etc when you are re-reading a print out 6 mths later and have no idea where the source came from.

The link embedding metaphor they use really is truly awful, and only midly worse than seeing a cryptic link - link text tottally abstracted from the actual link target...found this to be very common in blogs.

But wait there is a possible answer. Check out Aaron Gustafson's wonderfull article on alistapart http://www.alistapart.com/articles/improvingprint

I love the concept of all links referenced a la endnotes / footnotes. It's what I expect from technical literature, so why not standardise it's use on the web.

Klaus, that's a good read indeed and a good approach. I've thought about something similar to this. Content authors need to be careful with link wording. Otherwise they wouldn't make much sense in print (see Avoid Dead-End Hyperlinks, for example).

The site also falls apart in Safari if you venture past the first page or so.