Thoth wept, MSDN, where's the flaming table of contents?

[elfs]

For reasons, I ended up trying to read the documentation on LINQ, Microsoft's new DSL for refining collection lookups, i.e. sorting and looking stuff up in large datasets. It's a lot like embedded SQL, only performant with regular language features like lists and lookup tables.

MSDN's (Microsoft Developer Network) LINQ documentation page has an "outline" on the left side. The feature I wanted, "LINQ to XML," was not in the outline. I found it down at the bottom of the document. I clicked on it, and followed the links down through five different pages until I found, you know, actual examples.

The outline on the left is worthless. It obscures more than it shows. If I have to "open" a level of the outline, and all that does is show me what's on the page I'm currently looking at, then I'm not getting an index, I'm getting an index-shaped-thing that might help me once I'm completely familiar with the material. It's not searchable in-page using Ctrl-F, not when the content is hidden. As someone who learns best looking at other people's code, this was an exercise in frustration, and it really needs to be re-thought.

Comments

Thanks for this comment!

[maura van der linden (from livejournal.com)]

Thanks for posting this :) As I am currently on a committee at Borg working on how to make sample code more discoverable and usable, I'll take this commentary back to my working group.